{
"openapi": "3.0.0",
"info": {
"title": "Migranium Core API",
"description": "API documentation for Migranium Core Service - User Management & Authentication... "
},
"code": {
"description": "Secret key for manual entry in authenticator app",
"type": "string",
"example": "JBSWY3DPEHPK3PXP"
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/2fa/confirm": {
"post": {
"tags": [
"2FA"
],
"summary": "Confirm two-factor authentication",
"description": "Confirm 2FA setup for the user",
"operationId": "confirm2fa",
"requestBody": {
"description": "2FA confirmation code",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"example": "123456"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "2FA confirmed",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "2FA activated"
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/2fa/verify": {
"post": {
"tags": [
"2FA"
],
"summary": "Verify two-factor authentication",
"description": "Verify 2FA code for the user",
"operationId": "verify2fa",
"requestBody": {
"description": "2FA verification code and token",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"code",
"token"
],
"properties": {
"code": {
"type": "string",
"example": "123456"
},
"token": {
"type": "string",
"example": "temp-token-123"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "2FA verified, user logged in",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "Welcome back"
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/api/v1/auth/2fa/code/email": {
"post": {
"tags": [
"2FA"
],
"summary": "Send 2FA OTP by email",
"description": "Send a two-factor authentication OTP to the user's email",
"operationId": "emailOtp",
"requestBody": {
"description": "2FA email OTP request",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"type": "string",
"example": "temp-token-123"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OTP sent",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "2FA code sent to email"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/api/v1/auth/2fa/disable": {
"post": {
"tags": [
"2FA"
],
"summary": "Disable two-factor authentication",
"description": "Disable 2FA for the authenticated user",
"operationId": "disable2fa",
"responses": {
"200": {
"description": "2FA disabled",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "2FA disabled"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/2fa/status": {
"get": {
"tags": [
"2FA"
],
"summary": "Check 2FA status",
"description": "Check the status of two-factor authentication for the user",
"operationId": "status2fa",
"responses": {
"200": {
"description": "2FA status returned",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "2FA activated"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/2fa/skip": {
"post": {
"tags": [
"2FA"
],
"summary": "Skip two-factor authentication",
"description": "Skip 2FA for the user (e.g., for trusted devices)",
"operationId": "skip2fa",
"responses": {
"200": {
"description": "2FA skipped",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "Welcome back"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/2fa/reconfigure": {
"post": {
"tags": [
"2FA"
],
"summary": "Reconfigure two-factor authentication",
"description": "Reconfigure 2FA for the authenticated user",
"operationId": "reconfigure2fa",
"responses": {
"200": {
"description": "2FA reconfigured",
"content": {
"application/json": {
"schema": {
"properties": {
"qrcode": {
"type": "string",
"example": "... "
},
"code": {
"type": "string",
"example": "654321"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/resend-verification": {
"post": {
"tags": [
"Authentication"
],
"summary": "Resend email verification",
"description": "Resends the email verification link to the user's email address for users who haven't verified their email yet.",
"operationId": "resendVerification",
"requestBody": {
"description": "User's email to resend verification to",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"email"
],
"properties": {
"email": {
"description": "User's email address",
"type": "string",
"format": "email",
"maxLength": 255,
"example": "user@example.com"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Verification email sent successfully. The response is the same regardless of whether the email exists or is already verified to prevent user enumeration.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Verification email sent successfully"
},
"data": {
"type": "null",
"example": null
}
},
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/password/reset/{token}": {
"get": {
"tags": [
"Authentication"
],
"summary": "Verify password reset token",
"description": "Verifies the password reset token. If valid, it redirects to the frontend password reset page. If invalid, it redirects to the landing page. If expired, it returns an error.",
"operationId": "verifyPasswordReset",
"parameters": [
{
"name": "token",
"in": "path",
"description": "Password reset token sent to the user's email",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"302": {
"description": "Redirect to the frontend. To the reset password page if token is valid, or to the landing page if token is invalid."
},
"400": {
"description": "Bad Request. The token has expired.",
"content": {
"application/json": {
"schema": {
"properties": {
"errors": {
"properties": {
"token": {
"type": "array",
"items": {
"type": "string",
"example": "Expired"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/reset-password": {
"post": {
"tags": [
"Authentication"
],
"summary": "Reset user password",
"description": "Resets the user's password using a valid token.",
"operationId": "resetPassword",
"requestBody": {
"description": "Password reset data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"password",
"password_confirmation",
"token"
],
"properties": {
"password": {
"type": "string",
"format": "password",
"minLength": 8,
"example": "newpassword123"
},
"password_confirmation": {
"type": "string",
"format": "password",
"minLength": 8,
"example": "newpassword123"
},
"token": {
"type": "string",
"example": "a_valid_reset_token_from_email"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Password has been reset successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "Your password has been reset"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request. Invalid or expired token.",
"content": {
"application/json": {
"schema": {
"properties": {
"errors": {
"properties": {
"token": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid token."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"properties": {
"password": {
"type": "array",
"items": {
"type": "string",
"example": "The password must be at least 8 characters."
}
},
"token": {
"type": "array",
"items": {
"type": "string",
"example": "The selected token is invalid."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/logout": {
"put": {
"tags": [
"Authentication"
],
"summary": "Logout user",
"description": "Log out the authenticated user and revoke access token. This endpoint should be called when user explicitly logs out.",
"operationId": "logoutUser",
"responses": {
"200": {
"description": "Logout successful - Token revoked",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Logout complete. You have successfully signed out of your account."
},
"data": {
"type": "null",
"example": null
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or expired token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/first-login": {
"patch": {
"tags": [
"Authentication"
],
"summary": "Update first login flag",
"description": "Mark the authenticated user as having completed their first login by setting is_first_login to false.",
"operationId": "updateFirstLoginStatus",
"responses": {
"200": {
"description": "First login flag updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "First login status updated successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890",
"nullable": true
},
"profile_picture": {
"type": "string",
"example": "",
"nullable": true
},
"is_email_verified": {
"type": "boolean",
"example": true
},
"two_factor_enable": {
"type": "boolean",
"example": false
},
"business_count": {
"type": "integer",
"example": 1
},
"is_first_login": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/invitation/verify/{token}": {
"get": {
"tags": [
"Authentication"
],
"summary": "Verify team member invitation",
"description": "Verify a team member invitation token and return invitation details",
"operationId": "verifyTeamMemberInvitation",
"parameters": [
{
"name": "token",
"in": "path",
"description": "Team member invitation token",
"required": true,
"schema": {
"type": "string",
"example": "abc123invitationtoken"
}
}
],
"responses": {
"200": {
"description": "Invitation verified successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"properties": {
"invitation": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_email": {
"type": "string",
"example": "john.doe@example.com"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"business_name": {
"type": "string",
"example": "Acme Corp"
},
"business_id": {
"type": "integer",
"example": 1
},
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"status": {
"type": "string",
"example": "pending"
},
"expires_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-22T10:30:00Z"
}
},
"type": "object"
},
"is_existing_user": {
"type": "boolean",
"example": false
},
"requires_password": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"400": {
"description": "Invalid or expired invitation token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Invalid or expired invitation token"
]
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/invitation/accept": {
"post": {
"tags": [
"Authentication"
],
"summary": "Accept team member invitation",
"description": "Accept a team member invitation by providing a password and completing user setup. For new invitations, this creates the user account.",
"operationId": "acceptTeamMemberInvitation",
"requestBody": {
"description": "Invitation acceptance data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Team member invitation token",
"type": "string",
"example": "abc123invitationtoken"
},
"password": {
"description": "User password (minimum 8 characters, required for new users)",
"type": "string",
"format": "password",
"minLength": 8,
"example": "SecurePass123!"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Invitation accepted successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"properties": {
"temp_token": {
"description": "Temporary token for frontend redirect",
"type": "string",
"example": "temp-token-xyz789"
},
"redirect_url": {
"description": "URL to redirect user after acceptance",
"type": "string",
"example": "https://app.migranium.com/dashboard"
},
"is_new_user": {
"description": "Whether a new user account was created",
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"400": {
"description": "Invalid or expired invitation token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Invalid or expired invitation token"
]
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"password": [
"The password must be at least 8 characters."
]
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/invitations/pending": {
"get": {
"tags": [
"Authentication"
],
"summary": "Get pending invitations for authenticated user",
"description": "Returns all pending team member invitations for the currently logged-in user. Use this to show invitation popups after sign-in.",
"operationId": "getPendingInvitations",
"responses": {
"200": {
"description": "Pending invitations retrieved",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"properties": {
"invitations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"token": {
"type": "string",
"example": "abc123..."
},
"business_name": {
"type": "string",
"example": "Acme Corp"
},
"business_id": {
"type": "integer",
"example": 1
},
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"invited_by": {
"type": "string",
"example": "John Doe"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"count": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthenticated"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/invitation/accept-authenticated": {
"post": {
"tags": [
"Authentication"
],
"summary": "Accept invitation as authenticated user",
"description": "Accept a team member invitation as an already authenticated user. Used when existing users sign in and then accept the invitation. No password required.",
"operationId": "acceptInvitationAuthenticated",
"requestBody": {
"description": "Invitation acceptance data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Team member invitation token",
"type": "string",
"example": "abc123invitationtoken"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Invitation accepted successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"properties": {
"business_id": {
"type": "integer",
"example": 1
},
"business_name": {
"type": "string",
"example": "Acme Corp"
},
"redirect_url": {
"type": "string",
"example": "https://app.migranium.com/dashboard"
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"400": {
"description": "Invalid invitation or email mismatch"
},
"401": {
"description": "Unauthenticated"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/auth/invitation/decline": {
"post": {
"tags": [
"Authentication"
],
"summary": "Decline team member invitation",
"description": "Decline a team member invitation. The invitation will be marked as declined and cannot be used.",
"operationId": "declineTeamMemberInvitation",
"requestBody": {
"description": "Invitation decline data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Team member invitation token",
"type": "string",
"example": "abc123invitationtoken"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Invitation declined successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Invitation declined successfully"
},
"data": {
"type": "null",
"example": null
}
},
"type": "object"
}
]
}
}
}
},
"400": {
"description": "Invalid or expired invitation token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Invalid or expired invitation token"
]
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/google/callback": {
"post": {
"tags": [
"Authentication"
],
"summary": "Google OAuth callback endpoint",
"description": "Handle Google OAuth authentication callback. Supports both sign-in and sign-up flows. Verifies Google token and either logs in existing user or creates new user account.",
"operationId": "googleOAuthCallback",
"requestBody": {
"description": "Google OAuth callback data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Google OAuth access token from frontend",
"type": "string",
"example": "ya29.a0AfB_byC..."
},
"type": {
"description": "Authentication type - sign-in for existing users, sign-up for new users",
"type": "string",
"default": "sign-in",
"enum": [
"sign-in",
"sign-up"
],
"example": "sign-in"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Authentication successful",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Welcome back"
},
"data": {
"properties": {
"token": {
"type": "string",
"example": "jwt-token-xyz789"
},
"expires_in": {
"type": "integer",
"example": 3600
},
"two_factor_skip": {
"type": "boolean",
"example": true
},
"two_factor_enable": {
"type": "boolean",
"example": false
},
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"is_email_verified": {
"type": "boolean",
"example": true
},
"business_count": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"201": {
"description": "Two-factor authentication required",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Two-factor authentication required"
},
"data": {
"properties": {
"twoFactor": {
"type": "boolean",
"example": true
},
"token": {
"type": "string",
"example": "temp-token-abc123"
},
"expires_in": {
"type": "integer",
"example": 600
},
"two_factor_skip": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation error or authentication failure",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid Google token"
}
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/auth/microsoft/callback": {
"post": {
"tags": [
"Authentication"
],
"summary": "Microsoft OAuth callback endpoint",
"description": "Handle Microsoft OAuth authentication callback. Supports both sign-in and sign-up flows. Verifies Microsoft token and either logs in existing user or creates new user account.",
"operationId": "microsoftOAuthCallback",
"requestBody": {
"description": "Microsoft OAuth callback data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Microsoft OAuth access token from frontend",
"type": "string",
"example": "EwBwA8l6BAAU..."
},
"type": {
"description": "Authentication type - sign-in for existing users, sign-up for new users",
"type": "string",
"default": "sign-in",
"enum": [
"sign-in",
"sign-up"
],
"example": "sign-in"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Authentication successful",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Welcome back"
},
"data": {
"properties": {
"token": {
"type": "string",
"example": "jwt-token-xyz789"
},
"expires_in": {
"type": "integer",
"example": 3600
},
"two_factor_skip": {
"type": "boolean",
"example": true
},
"two_factor_enable": {
"type": "boolean",
"example": false
},
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"is_email_verified": {
"type": "boolean",
"example": true
},
"business_count": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"201": {
"description": "Two-factor authentication required",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Two-factor authentication required"
},
"data": {
"properties": {
"twoFactor": {
"type": "boolean",
"example": true
},
"token": {
"type": "string",
"example": "temp-token-abc123"
},
"expires_in": {
"type": "integer",
"example": 600
},
"two_factor_skip": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation error or authentication failure",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid Microsoft token"
}
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/automations/{automation_uuid}/actions": {
"get": {
"tags": [
"Automation"
],
"summary": "List automation actions",
"description": "Retrieve a paginated list of all actions for a specific automation",
"operationId": "a59e7be728d181109014cae115919928",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "automation_uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100,
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation actions retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationAction"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 25
},
"total_pages": {
"type": "integer",
"example": 2
},
"count": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Invalid business ID or missing header"
},
"401": {
"description": "Unauthenticated"
},
"403": {
"description": "Forbidden - User not authorized for this business"
},
"404": {
"description": "Automation not found"
},
"500": {
"description": "Internal server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations": {
"get": {
"tags": [
"Automation"
],
"summary": "Get all automations for a business",
"description": "Retrieve a paginated list of automations for the authenticated user's business",
"operationId": "getAutomations",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search in automation name and description",
"required": false,
"schema": {
"type": "string",
"example": "welcome email"
}
},
{
"name": "is_active",
"in": "query",
"description": "Filter by active status",
"required": false,
"schema": {
"type": "boolean",
"example": true
}
},
{
"name": "trigger_type",
"in": "query",
"description": "Filter by trigger type",
"required": false,
"schema": {
"type": "string",
"example": "patient_validation"
}
},
{
"name": "limit",
"in": "query",
"description": "Number of items per page (max 100)",
"required": false,
"schema": {
"type": "integer",
"example": 20
}
}
],
"responses": {
"200": {
"description": "Automations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Automation"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 25
},
"count": {
"type": "integer",
"example": 20
},
"per_page": {
"type": "integer",
"example": 20
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get automations."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Automation"
],
"summary": "Create a new automation",
"description": "Create a new automation with actions and optional owners",
"operationId": "createAutomation",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"trigger_type",
"actions"
],
"properties": {
"name": {
"description": "Name of the automation",
"type": "string",
"example": "Welcome Email Automation"
},
"description": {
"description": "Description of the automation",
"type": "string",
"example": "Sends welcome email to new patients"
},
"trigger_type": {
"description": "Type of trigger that activates this automation",
"type": "string",
"example": "patient_validation"
},
"start_date": {
"description": "Start date when automation becomes active",
"type": "string",
"format": "date",
"example": "2023-10-27"
},
"end_date": {
"description": "End date when automation becomes inactive",
"type": "string",
"format": "date",
"example": "2024-10-27"
},
"is_active": {
"description": "Whether the automation is currently active",
"type": "boolean",
"example": true
},
"status": {
"description": "Status of the automation (0 = draft, 1 = published)",
"type": "integer",
"example": 1
},
"settings": {
"description": "Additional settings for the automation",
"type": "object",
"example": {
"ui_config": {
"theme": "dark"
}
}
},
"actions": {
"type": "array",
"items": {
"required": [
"name",
"action_type",
"action_config"
],
"properties": {
"name": {
"description": "Name of the action",
"type": "string",
"example": "Send Welcome Email"
},
"action_type": {
"description": "Type of action to perform",
"type": "string",
"example": "send_email"
},
"action_config": {
"description": "Configuration for the action",
"type": "object",
"example": {
"to": "patient@example.com",
"subject": "Welcome",
"body": "Welcome message"
}
},
"execution_order": {
"description": "Order in which this action should be executed",
"type": "integer",
"example": 1
},
"is_active": {
"description": "Whether this action is active",
"type": "boolean",
"example": true
},
"operator": {
"description": "Operator for conditions",
"type": "string",
"example": "neutral"
},
"conditions": {
"description": "Conditions that must be met for this action to execute",
"type": "array",
"items": {
"type": "object"
}
},
"retry_config": {
"description": "Retry configuration for failed actions",
"type": "object"
}
},
"type": "object"
}
},
"apply_to_all_locations": {
"description": "Whether to apply this automation to all locations in the business",
"type": "boolean",
"example": false
},
"location_selections": {
"description": "Array of location selections for this automation",
"type": "array",
"items": {
"properties": {
"location_id": {
"description": "ID of the location",
"type": "integer",
"example": 1
},
"all_stations": {
"description": "Whether to include all stations in this location",
"type": "boolean",
"example": true
},
"station_ids": {
"description": "Array of station IDs to include (only used when all_stations is false)",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Automation created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation created successfully"
},
"data": {
"$ref": "#/components/schemas/Automation"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to create automation"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{uuid}": {
"get": {
"tags": [
"Automation"
],
"summary": "Get a specific automation",
"description": "Retrieve a specific automation by UUID",
"operationId": "getAutomation",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"responses": {
"200": {
"description": "Automation retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/Automation"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get automation."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Automation"
],
"summary": "Update an automation",
"description": "Update an existing automation with actions and optional owners",
"operationId": "updateAutomation",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Name of the automation",
"type": "string",
"example": "Updated Welcome Email Automation"
},
"description": {
"description": "Description of the automation",
"type": "string",
"example": "Updated description"
},
"trigger_type": {
"description": "Type of trigger that activates this automation",
"type": "string",
"example": "patient_validation"
},
"start_date": {
"description": "Start date when automation becomes active",
"type": "string",
"format": "date",
"example": "2023-10-27"
},
"end_date": {
"description": "End date when automation becomes inactive",
"type": "string",
"format": "date",
"example": "2024-10-27"
},
"is_active": {
"description": "Whether the automation is currently active",
"type": "boolean",
"example": true
},
"status": {
"description": "Status of the automation (0 = draft, 1 = published)",
"type": "integer",
"example": 1
},
"settings": {
"description": "Additional settings for the automation",
"type": "object",
"example": {
"ui_config": {
"theme": "dark"
}
}
},
"actions": {
"type": "array",
"items": {
"properties": {
"uuid": {
"description": "UUID of existing action (for updates)",
"type": "string",
"format": "uuid"
},
"name": {
"description": "Name of the action",
"type": "string",
"example": "Send Welcome Email"
},
"action_type": {
"description": "Type of action to perform",
"type": "string",
"example": "send_email"
},
"action_config": {
"description": "Configuration for the action",
"type": "object",
"example": {
"to": "patient@example.com",
"subject": "Welcome",
"body": "Welcome message"
}
},
"execution_order": {
"description": "Order in which this action should be executed",
"type": "integer",
"example": 1
},
"is_active": {
"description": "Whether this action is active",
"type": "boolean",
"example": true
},
"operator": {
"description": "Operator for conditions",
"type": "string",
"example": "neutral"
},
"conditions": {
"description": "Conditions that must be met for this action to execute",
"type": "array",
"items": {
"type": "object"
}
},
"retry_config": {
"description": "Retry configuration for failed actions",
"type": "object"
}
},
"type": "object"
}
},
"apply_to_all_locations": {
"description": "Whether to apply this automation to all locations in the business",
"type": "boolean",
"example": false
},
"location_selections": {
"description": "Array of location selections for this automation",
"type": "array",
"items": {
"properties": {
"location_id": {
"description": "ID of the location",
"type": "integer",
"example": 1
},
"all_stations": {
"description": "Whether to include all stations in this location",
"type": "boolean",
"example": true
},
"station_ids": {
"description": "Array of station IDs to include (only used when all_stations is false)",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Automation updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation updated successfully"
},
"data": {
"$ref": "#/components/schemas/Automation"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to update automation."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Automation"
],
"summary": "Delete an automation",
"description": "Delete an automation by UUID",
"operationId": "deleteAutomation",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"responses": {
"200": {
"description": "Automation deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation deleted successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to delete automation."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/bulk-delete": {
"delete": {
"tags": [
"Automation"
],
"summary": "Delete multiple automations",
"description": "Delete multiple automations by their UUIDs",
"operationId": "deleteMultipleAutomations",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"uuids"
],
"properties": {
"uuids": {
"description": "Array of automation UUIDs to delete",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"123e4567-e89b-12d3-a456-426614174000",
"123e4567-e89b-12d3-a456-426614174001"
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Automations deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automations deleted successfully"
},
"data": {
"properties": {
"deleted_count": {
"description": "Number of automations deleted",
"type": "integer",
"example": 2
},
"not_found_count": {
"description": "Number of automations not found",
"type": "integer",
"example": 0
},
"deleted_uuids": {
"description": "Array of successfully deleted automation UUIDs",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"123e4567-e89b-12d3-a456-426614174000",
"123e4567-e89b-12d3-a456-426614174001"
]
},
"not_found_uuids": {
"description": "Array of automation UUIDs that were not found",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": []
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to delete automations."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/stats": {
"get": {
"tags": [
"Automation"
],
"summary": "Get automation statistics",
"description": "Get statistics for automations in a business",
"operationId": "getAutomationStats",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Statistics retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"total": {
"description": "Total number of automations",
"type": "integer",
"example": 10
},
"active": {
"description": "Number of active automations",
"type": "integer",
"example": 7
},
"inactive": {
"description": "Number of inactive automations",
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get automation stats."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/action-types": {
"get": {
"tags": [
"Automation"
],
"summary": "Get automation action types",
"description": "Get all available automation action types, optionally filtered by trigger type",
"operationId": "getAutomationActionTypes",
"parameters": [
{
"name": "trigger_type",
"in": "query",
"description": "Filter action types by applicable trigger type",
"required": false,
"schema": {
"type": "string",
"example": "patient_access_started"
}
}
],
"responses": {
"200": {
"description": "Action types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationActionType"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get action types"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/trigger-types": {
"get": {
"tags": [
"Automation"
],
"summary": "Get automation trigger types",
"description": "Get all available automation trigger types",
"operationId": "getAutomationTriggerTypes",
"responses": {
"200": {
"description": "Trigger types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationTriggerType"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get trigger types"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/condition-types": {
"get": {
"tags": [
"Automation"
],
"summary": "Get automation condition types",
"description": "Get all available automation condition types, optionally filtered by trigger type",
"operationId": "getAutomationConditionTypes",
"parameters": [
{
"name": "trigger_type",
"in": "query",
"description": "Filter condition types by applicable trigger type",
"required": false,
"schema": {
"type": "string",
"example": "patient_access_started"
}
}
],
"responses": {
"200": {
"description": "Condition types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationConditionType"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get condition types"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/check-types": {
"get": {
"tags": [
"Automation"
],
"summary": "Get automation check types",
"description": "Get all available automation check types, optionally filtered by trigger type",
"operationId": "getAutomationCheckTypes",
"parameters": [
{
"name": "trigger_type",
"in": "query",
"description": "Filter check types by applicable trigger type",
"required": false,
"schema": {
"type": "string",
"example": "patient_access_started"
}
}
],
"responses": {
"200": {
"description": "Check types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationCheckType"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get check types"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{uuid}/test": {
"post": {
"tags": [
"Automation"
],
"summary": "Test automation execution",
"description": "Test if an automation can run successfully with sample data",
"operationId": "testAutomation",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Automation UUID to test",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"test_data": {
"description": "Sample data for testing the automation",
"type": "object",
"example": {
"patient_id": 123,
"email": "test@example.com"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Automation test completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation test run successful!"
},
"data": {
"properties": {
"automation_name": {
"type": "string",
"example": "Welcome Email Automation"
},
"overall_status": {
"type": "string",
"example": "success"
},
"execution_time": {
"type": "number",
"format": "float",
"example": 0.245
},
"steps": {
"properties": {
"trigger": {
"properties": {
"name": {
"type": "string",
"example": "Trigger is Patient Validation"
},
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Trigger validation passed"
}
},
"type": "object"
},
"condition": {
"properties": {
"name": {
"type": "string",
"example": "Conditions: patient_id = 123, email = test@example.com"
},
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Conditions validation passed"
}
},
"type": "object"
},
"actions": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "Send Welcome Email"
},
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Action executed successfully"
},
"error": {
"type": "string",
"example": null
}
},
"type": "object"
}
},
"check": {
"properties": {
"name": {
"type": "string",
"example": "Standard execution - no special checks configured"
},
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Check configuration valid"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Automation validation failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation validation failed"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to test automation"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{uuid}/check-duplicates": {
"post": {
"tags": [
"Automation"
],
"summary": "Check for duplicate automations based on automation ID",
"description": "Check for existing automations with the same business, owners, and configuration as the specified automation",
"operationId": "checkDuplicateAutomationById",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Automation UUID to check duplicates for",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"responses": {
"200": {
"description": "Duplicate check completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"matching_actions_count": {
"description": "Total number of matching actions found",
"type": "integer",
"example": 5
},
"non_matching_actions_count": {
"description": "Total number of non-matching actions found",
"type": "integer",
"example": 3
},
"matching_actions": {
"description": "List of matching actions with details",
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "Send Welcome Email"
},
"action_type": {
"type": "string",
"example": "send_email"
},
"execution_order": {
"type": "integer",
"example": 1
},
"action_config": {
"type": "object",
"example": {
"to": "patient@example.com",
"subject": "Welcome",
"body": "Welcome message"
}
}
},
"type": "object"
}
},
"non_matching_actions": {
"description": "List of non-matching actions with details",
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "Send Follow-up Email"
},
"action_type": {
"type": "string",
"example": "send_email"
},
"execution_order": {
"type": "integer",
"example": 2
},
"action_config": {
"type": "object",
"example": {
"to": "patient@example.com",
"subject": "Follow-up",
"body": "Follow-up message"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to check duplicates"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/automations/{automation_uuid}/executions/{execution_id}/failed-detail": {
"get": {
"tags": [
"Automation"
],
"summary": "Get failed automation execution detail",
"description": "Retrieve detailed information about a failed automation execution for testing purposes",
"operationId": "getFailedAutomationExecutionDetail",
"parameters": [
{
"name": "automation_uuid",
"in": "path",
"description": "UUID of the automation",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
},
{
"name": "execution_id",
"in": "path",
"description": "ID of the execution",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Failed execution detail retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Failed execution detail retrieved successfully"
},
"data": {
"properties": {
"execution_id": {
"type": "integer",
"example": 123
},
"automation_uuid": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"automation_name": {
"type": "string",
"example": "Patient Appointment Reminder"
},
"overall_status": {
"type": "string",
"example": "failed"
},
"overall_message": {
"type": "string",
"example": "Automation test run failed"
},
"execution_time": {
"type": "number",
"format": "float",
"example": 0.045
},
"error_message": {
"type": "string",
"example": "SMTP connection failed"
},
"error_code": {
"type": "string",
"example": "EMAIL_SERVICE_ERROR"
},
"retry_count": {
"type": "integer",
"example": 2
},
"max_retries": {
"type": "integer",
"example": 5
},
"steps": {
"properties": {
"trigger": {
"properties": {
"name": {
"type": "string",
"example": "Trigger is Appointment Scheduled"
},
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Success"
}
},
"type": "object"
},
"condition": {
"properties": {
"name": {
"type": "string",
"example": "Category check is Blueberry, Gen Z, Millennium, Assessments, Report Review, Immunizations, Follow Up Consultation, Cancer Screening, Mental Health Assessment, Referral Appointment, Assessments"
},
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Success"
}
},
"type": "object"
},
"action_if_match": {
"properties": {
"name": {
"type": "string",
"example": "Then Redirect To Registration Form and Create an account"
},
"status": {
"type": "string",
"example": "failed"
},
"message": {
"type": "string",
"example": "Failed"
},
"error_detail": {
"type": "string",
"example": "Couldn't sent the registration form."
}
},
"type": "object"
},
"action_if_not_match": {
"properties": {
"name": {
"type": "string",
"example": "Then sent Form: http://examplelink.com"
},
"status": {
"type": "string",
"example": "not_executed"
},
"message": {
"type": "string",
"example": "-"
}
},
"type": "object"
},
"check": {
"properties": {
"name": {
"type": "string",
"example": "Will check for Form submission in every 48 hours"
},
"status": {
"type": "string",
"example": "not_executed"
},
"message": {
"type": "string",
"example": "-"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Execution not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Execution not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to retrieve execution detail"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{uuid}/execution-history": {
"get": {
"tags": [
"Automation"
],
"summary": "Get automation execution history",
"description": "Get execution history for a specific automation with dummy data",
"operationId": "getAutomationExecutionHistory",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "limit",
"in": "query",
"description": "Number of items per page (max 100)",
"required": false,
"schema": {
"type": "integer",
"example": 20
}
}
],
"responses": {
"200": {
"description": "Execution history retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation execution history retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"description": "Execution record ID",
"type": "integer",
"example": 1
},
"patient_name": {
"description": "Patient name",
"type": "string",
"example": "John Doe"
},
"patient_email": {
"description": "Patient email",
"type": "string",
"example": "john.doe@example.com"
},
"action": {
"description": "Action performed",
"type": "string",
"example": "Appointment Schedule"
},
"run_time": {
"description": "When the action was executed",
"type": "string",
"format": "date-time",
"example": "2023-05-15 08:00:00"
},
"status": {
"description": "Execution status (Successful/Failed)",
"type": "string",
"example": "Successful"
},
"execution_duration": {
"description": "Execution duration in milliseconds",
"type": "integer",
"example": 1500
},
"error_message": {
"description": "Error message if failed",
"type": "string",
"example": ""
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 150
},
"count": {
"type": "integer",
"example": 20
},
"per_page": {
"type": "integer",
"example": 20
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 8
}
},
"type": "object"
},
"summary": {
"properties": {
"total_executions": {
"type": "integer",
"example": 150
},
"successful_executions": {
"type": "integer",
"example": 135
},
"failed_executions": {
"type": "integer",
"example": 15
},
"success_rate": {
"type": "number",
"format": "float",
"example": 90
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to get execution history."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{uuid}/rerun-execution/{execution_id}": {
"post": {
"tags": [
"Automation"
],
"summary": "Rerun a specific execution",
"description": "Rerun a specific execution by its ID",
"operationId": "rerunSpecificExecution",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
},
{
"name": "execution_id",
"in": "path",
"description": "Execution ID to rerun",
"required": true,
"schema": {
"type": "integer",
"example": 15
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"max_retries": {
"description": "Maximum number of retry attempts (default: 3)",
"type": "integer",
"example": 3
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Execution rerun successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Execution rerun successfully"
},
"data": {
"properties": {
"execution_id": {
"description": "The execution ID that was rerun",
"type": "integer",
"example": 15
},
"status": {
"description": "Result of the rerun attempt",
"type": "string",
"example": "Successful"
},
"execution_duration": {
"description": "Execution duration in milliseconds",
"type": "integer",
"example": 1500
},
"error_message": {
"description": "Error message if failed",
"type": "string",
"example": ""
},
"retry_count": {
"description": "Number of retry attempts made",
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation or execution not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation or execution not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"max_retries": "Max retries must be between 1 and 10"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to rerun execution."
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{uuid}/toggle-active": {
"patch": {
"tags": [
"Automation"
],
"summary": "Toggle automation active status",
"description": "Toggle the is_active status of an automation",
"operationId": "toggleAutomationActive",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "uuid",
"in": "path",
"description": "Automation UUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Automation status toggled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Automation activated successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Automation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Automation not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/automations/bulk-toggle-status": {
"post": {
"tags": [
"Automation"
],
"summary": "Bulk update automation active status",
"operationId": "8b36612d946356b07026a79e436ecd1c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"automation_uuids",
"is_active"
],
"properties": {
"automation_uuids": {
"description": "Array of automation UUIDs to update status",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
},
"is_active": {
"description": "The status to set for all automations (true = active, false = inactive)",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Bulk status update completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Bulk status update completed successfully"
},
"data": {
"properties": {
"updated_count": {
"description": "Number of automations updated",
"type": "integer",
"example": 5
},
"not_found_count": {
"description": "Number of automations not found",
"type": "integer",
"example": 1
},
"target_status": {
"description": "The status that was set",
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automation-types/trigger-types": {
"get": {
"tags": [
"Automation"
],
"summary": "List all trigger types",
"description": "Retrieve a paginated list of all automation trigger types",
"operationId": "6f0fee51aeaa083e1b3a37005b09cb26",
"parameters": [
{
"name": "X-Business-ID",
"in": "header",
"description": "Business ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"schema": {
"type": "integer",
"default": 15
}
},
{
"name": "active",
"in": "query",
"description": "Filter by active status",
"schema": {
"type": "boolean"
}
},
{
"name": "is_system",
"in": "query",
"description": "Filter by system/custom types",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"trigger_type": {
"type": "string",
"example": "patient_validation"
},
"name": {
"type": "string",
"example": "Patient Validation"
},
"description": {
"type": "string",
"example": "Triggered when a patient account is validated"
},
"config_schema": {
"type": "object",
"example": {
"type": "object",
"properties": []
}
},
"default_config": {
"type": "object",
"example": []
},
"is_active": {
"type": "boolean",
"example": true
},
"is_system": {
"type": "boolean",
"example": true
},
"sort_order": {
"type": "integer",
"example": 1
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 6
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Missing/invalid business ID or invalid query parameters",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request"
},
"errors": {
"type": "object",
"example": {
"business_id": [
"Missing business ID header."
],
"active": [
"The active field must be true or false."
]
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Bad request - Invalid query parameters",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid query parameters"
},
"errors": {
"type": "object",
"example": {
"active": [
"The active field must be true or false."
],
"is_system": [
"The is system field must be true or false."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden - User not authorized for this business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized for this business"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Business not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"No business found for the given business ID."
]
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/banners/{type}": {
"get": {
"tags": [
"Banners"
],
"summary": "Get banners by type",
"operationId": "c41af8146423a97751e3ff57e613f2ac",
"parameters": [
{
"name": "type",
"in": "path",
"description": "Banner type",
"required": true,
"schema": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
}
}
],
"responses": {
"200": {
"description": "Banners retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banners retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Banner"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Banners"
],
"summary": "Create a new banner by type",
"operationId": "c601e4e2143353e2fb1371ba30a70880",
"parameters": [
{
"name": "type",
"in": "path",
"description": "Banner type",
"required": true,
"schema": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"example": "Welcome to our service"
},
"is_active": {
"type": "boolean",
"example": true
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Banner created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner created successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/banners/{id}/toggle-status": {
"patch": {
"tags": [
"Banners"
],
"summary": "Toggle banner active status",
"operationId": "33040e4bebc5f752553ff8406dac0124",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Banner status toggled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner status toggled successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/locations/{location_id}/banners/{type}": {
"get": {
"tags": [
"Banners"
],
"summary": "Get banners by type for a specific location",
"operationId": "753973b9312e4b69ad52c79b0e1cce49",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "path",
"description": "Banner type",
"required": true,
"schema": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
}
}
],
"responses": {
"200": {
"description": "Location banners retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Location banners retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Banner"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Banners"
],
"summary": "Create a new banner for a specific location by type",
"operationId": "925624a6c80e41a3e3997faa8496cca7",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "path",
"description": "Banner type",
"required": true,
"schema": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"example": "Welcome to our service"
},
"is_active": {
"type": "boolean",
"example": true
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Banner created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner created successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/locations/{location_id}/banners/{id}": {
"put": {
"tags": [
"Banners"
],
"summary": "Update a banner for a specific location",
"operationId": "b6061c9f8f3df83301b2a26230ec4c6c",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"description": {
"type": "string",
"example": "Updated description"
},
"type": {
"type": "string",
"default": "scheduling",
"enum": [
"scheduling",
"walk-in"
]
},
"is_active": {
"type": "boolean",
"example": true
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Banner updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner updated successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner or location not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Banners"
],
"summary": "Delete a banner for a specific location",
"operationId": "5def15958f5491ac840da2ef13cc9255",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Banner deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner deleted successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner or location not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/locations/{location_id}/stations/{station_id}/banners/{id}": {
"put": {
"tags": [
"Banners"
],
"summary": "Update a banner for a specific location-station",
"operationId": "f514b6f1ba93ea4b788ea993900f1190",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"description": {
"type": "string",
"example": "Updated description"
},
"type": {
"type": "string",
"default": "scheduling",
"enum": [
"scheduling",
"walk-in"
]
},
"is_active": {
"type": "boolean",
"example": true
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Banner updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner updated successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner or location-station not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Banners"
],
"summary": "Delete a banner for a specific location-station",
"operationId": "201be26ee717e1785f3cc462d3bacbe8",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Banner deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner deleted successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner or location-station not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/locations/{location_id}/stations/{station_id}/banners/{type}": {
"get": {
"tags": [
"Banners"
],
"summary": "Get banners by type for a specific location-station",
"operationId": "5a494a41c08ddacb80696bb7d6595964",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "path",
"description": "Banner type",
"required": true,
"schema": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
}
}
],
"responses": {
"200": {
"description": "Location-station banners retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Location-station banners retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Banner"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location or station not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Banners"
],
"summary": "Create a new banner for a specific location-station by type",
"operationId": "f19e1c31584e58324a0e958fc9364e8c",
"parameters": [
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "path",
"description": "Banner type",
"required": true,
"schema": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"example": "Welcome to our service"
},
"is_active": {
"type": "boolean",
"example": true
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Banner created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner created successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location or station not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/banners/{id}": {
"put": {
"tags": [
"Banners"
],
"summary": "Update a banner",
"operationId": "8f79ca726f00a66e9302e55bf9a81338",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"description": {
"type": "string",
"example": "Updated banner description"
},
"type": {
"type": "string",
"enum": [
"scheduling",
"walk-in"
]
},
"is_active": {
"type": "boolean",
"example": true
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Banner updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner updated successfully"
},
"data": {
"$ref": "#/components/schemas/Banner"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Banners"
],
"summary": "Delete a banner",
"operationId": "546d91dcb16c58f59da98c6ce52a011e",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Banner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Banner deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Banner deleted successfully"
},
"data": {
"type": "null"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Banner not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/business-categories": {
"get": {
"tags": [
"Business Categories"
],
"summary": "Get all business categories",
"description": "Retrieve a list of all available business categories with optional pagination, search, and sorting",
"operationId": "getBusinessCategories",
"parameters": [
{
"name": "search",
"in": "query",
"description": "Search business categories by name",
"required": false,
"schema": {
"type": "string",
"example": "hospital"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"id"
],
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (1-100). If not provided, returns all data.",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 10
}
}
],
"responses": {
"200": {
"description": "Business categories retrieved successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Business categories retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Hospital"
}
},
"type": "object"
}
},
"meta": {
"description": "Pagination metadata (only when per_page is provided)",
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 2
},
"per_page": {
"type": "integer",
"example": 10
},
"total": {
"type": "integer",
"example": 15
},
"from": {
"type": "integer",
"example": 1
},
"to": {
"type": "integer",
"example": 10
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/partners": {
"get": {
"tags": [
"Business Partners"
],
"summary": "Get all partner businesses",
"description": "Retrieve a list of all businesses that are partners with the current organization",
"operationId": "getBusinessPartners",
"parameters": [
{
"name": "per_page",
"in": "query",
"description": "Number of partners per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Filter partners whose name or email matches the given text",
"schema": {
"type": "string",
"example": "clinic"
}
},
{
"name": "partner_type_id",
"in": "query",
"description": "Filter partners by partner type ID (supports comma-separated list)",
"schema": {
"type": "string",
"example": "1,2"
}
}
],
"responses": {
"200": {
"description": "Partners retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partners retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BusinessDetails"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Business not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Business Partners"
],
"summary": "Add a new partner business",
"description": "Create a new partner business with a default location and establish a partnership relationship",
"operationId": "addBusinessPartner",
"requestBody": {
"description": "Partner business details",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"email"
],
"properties": {
"name": {
"description": "Partner organization name",
"type": "string",
"example": "Partner Medical Clinic"
},
"email": {
"description": "Partner email address",
"type": "string",
"format": "email",
"example": "partner@clinic.com"
},
"phone": {
"description": "Partner phone number",
"type": "string",
"example": "+1-555-987-6543"
},
"address": {
"description": "Partner street address",
"type": "string",
"example": "456 Partner Street"
},
"country": {
"description": "Partner country",
"type": "string",
"example": "United States"
},
"state": {
"description": "Partner province/state",
"type": "string",
"example": "California"
},
"city": {
"description": "Partner city",
"type": "string",
"example": "Los Angeles"
},
"business_category_id": {
"description": "Business category ID (optional)",
"type": "integer",
"example": 1
},
"first_name": {
"description": "First name of user for the partner business (uses email field for user)",
"type": "string",
"example": "John"
},
"last_name": {
"description": "Last name of user for the partner business (uses email field for user)",
"type": "string",
"example": "Doe"
},
"partner_type_id": {
"description": "Partner type identifier",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Partner created and added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner added successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Validation failed"
},
"404": {
"description": "Business not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Bulk remove partner businesses",
"description": "Remove multiple partnerships between the current business and partner businesses",
"operationId": "bulkRemoveBusinessPartners",
"requestBody": {
"description": "List of partner business IDs to remove",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"partner_ids"
],
"properties": {
"partner_ids": {
"type": "array",
"items": {
"type": "integer",
"example": 12
},
"example": [
12,
45,
78
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Partners removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Selected partners removed successfully"
},
"data": {
"properties": {
"removed_partner_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"not_found_partner_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"removed_count": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "No matching partnerships found"
},
"422": {
"description": "Validation error"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/types": {
"get": {
"tags": [
"Business Partners"
],
"summary": "List partner types",
"description": "Retrieve a list of available partner types.",
"operationId": "listPartnerTypes",
"parameters": [
{
"name": "per_page",
"in": "query",
"description": "Number of partner types per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Partner types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner types retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Refral"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}": {
"get": {
"tags": [
"Business Partners"
],
"summary": "Get partner details",
"description": "Retrieve detailed information about a specific partner business.",
"operationId": "getPartnerDetails",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"responses": {
"200": {
"description": "Partner retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/BusinessDetails"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Business Partners"
],
"summary": "Update partner business details",
"description": "Update general information and partner type for an existing partner business",
"operationId": "updateBusinessPartner",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 42
}
}
],
"requestBody": {
"description": "Partner business details to update",
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Partner organization name",
"type": "string",
"example": "Partner Medical Clinic"
},
"email": {
"description": "Partner email address",
"type": "string",
"format": "email",
"example": "partner@clinic.com"
},
"phone": {
"description": "Partner phone number",
"type": "string",
"example": "+1-555-987-6543"
},
"address": {
"description": "Partner street address",
"type": "string",
"example": "456 Partner Street"
},
"country": {
"description": "Partner country",
"type": "string",
"example": "United States"
},
"state": {
"description": "Partner province/state",
"type": "string",
"example": "California"
},
"city": {
"description": "Partner city",
"type": "string",
"example": "Los Angeles"
},
"business_category_id": {
"description": "Business category ID",
"type": "integer",
"example": 1
},
"partner_type_id": {
"description": "Partner type identifier",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Partner updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner updated successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Remove a partner business",
"description": "Remove a partnership between two businesses",
"operationId": "removeBusinessPartner",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID to remove",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Partner removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner removed successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Business or partnership not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/locations/{location_id}/stations-services": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Create a partner station with services",
"description": "Create a new station for the specified partner location and attach one or more services to the same location-station relationship.",
"operationId": "addPartnerStationWithServices",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 27
}
},
{
"name": "location_id",
"in": "path",
"description": "Location ID that belongs to the partner business",
"required": true,
"schema": {
"type": "integer",
"example": 101
}
}
],
"requestBody": {
"description": "Station and services payload",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station",
"services"
],
"properties": {
"station": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Downtown Clinic Room 3"
},
"description": {
"type": "string",
"example": "Dedicated Telehealth Room",
"nullable": true
},
"image": {
"type": "string",
"example": "https://example.com/station.png",
"nullable": true
}
},
"type": "object"
},
"services": {
"type": "array",
"items": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Telehealth Consultation"
},
"description": {
"type": "string",
"example": "30 minute consultation",
"nullable": true
},
"time_in_minute": {
"type": "integer",
"example": 30
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Station and services created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner station and services created successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed"
},
"404": {
"description": "Partner or location not found"
},
"400": {
"description": "Bad request - No partnership exists with this business"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/locations/{location_id}/stations/{station_id}/services": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Add services to an existing partner station",
"description": "Create one or more services for an existing partner station within the specified location, ensuring the services are attached to the station and the location-station pivot.",
"operationId": "addPartnerServicesToStation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 27
}
},
{
"name": "location_id",
"in": "path",
"description": "Location ID that belongs to the partner business",
"required": true,
"schema": {
"type": "integer",
"example": 101
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID that belongs to the partner business",
"required": true,
"schema": {
"type": "integer",
"example": 55
}
}
],
"requestBody": {
"description": "Services payload",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"services"
],
"properties": {
"services": {
"type": "array",
"items": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Telehealth Consultation"
},
"description": {
"type": "string",
"example": "30 minute consultation",
"nullable": true
},
"time_in_minute": {
"type": "integer",
"example": 30
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Services created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner services created successfully for station"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed"
},
"404": {
"description": "Partner, location, or station not found"
},
"400": {
"description": "Bad request - No partnership exists with this business"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/team-members": {
"get": {
"tags": [
"Business Partners"
],
"summary": "List partner team members",
"description": "Retrieve all team members belonging to the specified partner business.",
"operationId": "listPartnerTeamMembers",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"responses": {
"200": {
"description": "Team members retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner team members retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 45
},
"user_id": {
"type": "integer",
"example": 123
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "jane.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"is_owner": {
"type": "boolean",
"example": false
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "SERVICE_PROVIDER"
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Clinic"
}
},
"type": "object"
}
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 10
},
"name": {
"type": "string",
"example": "Consultation Room A"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-24T06:21:00Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Business Partners"
],
"summary": "Create partner team member",
"description": "Create or invite a team member for the specified partner business.",
"operationId": "createPartnerTeamMember",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"first_name",
"last_name",
"email"
],
"properties": {
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"format": "email",
"example": "jane.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"is_owner": {
"type": "boolean",
"example": false
},
"roles": {
"type": "array",
"items": {
"required": [
"role"
],
"properties": {
"role": {
"type": "string",
"enum": [
"BUSINESS_MANAGER",
"LOCATION_MANAGER",
"STATION_MANAGER",
"SERVICE_PROVIDER",
"TEAM_MEMBER"
],
"example": "TEAM_MEMBER"
},
"location_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
],
"nullable": true
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
10,
11
],
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Team member created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner team member added successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 45
},
"user_id": {
"type": "integer",
"example": 123
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "jane.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"is_owner": {
"type": "boolean",
"example": false
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-24T06:21:00Z"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Clinic"
}
},
"type": "object"
}
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 10
},
"name": {
"type": "string",
"example": "Consultation Room A"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/team-members/{team_member_id}": {
"get": {
"tags": [
"Business Partners"
],
"summary": "Get partner team member detail",
"description": "Retrieve a single team member belonging to the specified partner business.",
"operationId": "showPartnerTeamMember",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "team_member_id",
"in": "path",
"description": "Partner team member identifier",
"required": true,
"schema": {
"type": "integer",
"example": 45
}
}
],
"responses": {
"200": {
"description": "Team member retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner team member retrieved successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 45
},
"user_id": {
"type": "integer",
"example": 123
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "jane.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"is_owner": {
"type": "boolean",
"example": false
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-24T06:21:00Z"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Clinic"
}
},
"type": "object"
}
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 10
},
"name": {
"type": "string",
"example": "Consultation Room A"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner team member not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Business Partners"
],
"summary": "Update partner team member",
"description": "Update details for a partner team member, including roles and ownership.",
"operationId": "updatePartnerTeamMember",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "team_member_id",
"in": "path",
"description": "Partner team member identifier",
"required": true,
"schema": {
"type": "integer",
"example": 45
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"is_owner": {
"type": "boolean",
"example": false
},
"roles": {
"type": "array",
"items": {
"required": [
"role"
],
"properties": {
"role": {
"type": "string",
"enum": [
"BUSINESS_MANAGER",
"LOCATION_MANAGER",
"STATION_MANAGER",
"SERVICE_PROVIDER",
"TEAM_MEMBER"
],
"example": "TEAM_MEMBER"
},
"location_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
],
"nullable": true
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
10,
11
],
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Team member updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner team member updated successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 45
},
"user_id": {
"type": "integer",
"example": 123
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "jane.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"is_owner": {
"type": "boolean",
"example": false
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-24T06:21:00Z"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Clinic"
}
},
"type": "object"
}
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 10
},
"name": {
"type": "string",
"example": "Consultation Room A"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner team member not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Remove partner team member",
"description": "Remove a team member from the specified partner business.",
"operationId": "removePartnerTeamMember",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "team_member_id",
"in": "path",
"description": "Partner team member identifier",
"required": true,
"schema": {
"type": "integer",
"example": 45
}
}
],
"responses": {
"200": {
"description": "Team member removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner team member removed successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Attempted to remove partner owner"
},
"404": {
"description": "Partner team member not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/team-members/bulk-delete": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Bulk remove partner team members",
"description": "Remove multiple team members from the specified partner business. Partners must have at least one team member at all times.",
"operationId": "bulkRemovePartnerTeamMembers",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"team_member_ids"
],
"properties": {
"team_member_ids": {
"description": "UserBusiness IDs of team members to remove",
"type": "array",
"items": {
"type": "integer"
},
"example": [
45,
46,
47
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Team members removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner team members removed successfully"
},
"data": {
"properties": {
"deleted": {
"type": "integer",
"example": 3
},
"processed": {
"type": "integer",
"example": 3
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Attempted to remove all team members or remove owner"
},
"404": {
"description": "Partner business not found"
},
"422": {
"description": "Validation error"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/locations/{location_id}/stations-services/assign": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Assign partner services to stations",
"description": "Assign one or multiple services to multiple partner stations at the specified location.",
"operationId": "assignPartnerServicesToStations",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "location_id",
"in": "path",
"description": "Partner Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 45
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"assignments"
],
"properties": {
"assignments": {
"type": "array",
"items": {
"properties": {
"station_id": {
"description": "Single station ID (deprecated in favour of station_ids array)",
"type": "integer",
"example": 67
},
"station_ids": {
"description": "One or more station IDs to assign the services to",
"type": "array",
"items": {
"type": "integer",
"example": 67
}
},
"services": {
"description": "Optional services to assign to the station(s). When omitted, only station validation occurs.",
"type": "array",
"items": {
"required": [
"service_id"
],
"properties": {
"service_id": {
"type": "integer",
"example": 123
},
"time_in_minute": {
"type": "integer",
"minimum": 1,
"example": 30
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services assigned successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner service assigned successfully"
},
"data": {
"properties": {
"assigned": {
"type": "integer",
"example": 4
},
"items": {
"type": "array",
"items": {
"properties": {
"service_id": {
"type": "integer",
"example": 123
},
"station_id": {
"type": "integer",
"example": 67
},
"location_id": {
"type": "integer",
"example": 45
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business, location, station, or service not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/locations": {
"get": {
"tags": [
"Business Partners"
],
"summary": "List partner locations",
"description": "Retrieve all locations belonging to the specified partner business.",
"operationId": "listPartnerLocations",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "search",
"in": "query",
"description": "Filter locations by matching text in the name, address, city, state, country, or phone number",
"schema": {
"type": "string",
"example": "Downtown"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of locations per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner locations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetail"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Business Partners"
],
"summary": "Add a new location for a partner business",
"description": "Create a new location for an existing partner business that shares a partnership with the current organization.",
"operationId": "addLocationToPartner",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 27
}
}
],
"requestBody": {
"description": "Location details",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Downtown Clinic"
},
"address": {
"type": "string",
"maxLength": 255,
"example": "123 Main Street",
"nullable": true
},
"city": {
"type": "string",
"maxLength": 100,
"example": "Austin",
"nullable": true
},
"state": {
"type": "string",
"maxLength": 100,
"example": "TX",
"nullable": true
},
"country": {
"type": "string",
"maxLength": 100,
"example": "USA",
"nullable": true
},
"phone_number": {
"type": "string",
"maxLength": 50,
"example": "+1 555-0100",
"nullable": true
},
"description": {
"type": "string",
"example": "Primary intake location for referrals.",
"nullable": true
},
"image": {
"type": "string",
"example": "https://example.com/location.png",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Location created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Location added successfully to partner business"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 101
},
"name": {
"type": "string",
"example": "Downtown Clinic"
},
"address": {
"type": "string",
"example": "123 Main Street",
"nullable": true
},
"city": {
"type": "string",
"example": "Austin",
"nullable": true
},
"state": {
"type": "string",
"example": "TX",
"nullable": true
},
"country": {
"type": "string",
"example": "USA",
"nullable": true
},
"phone_number": {
"type": "string",
"example": "+1 555-0100",
"nullable": true
},
"description": {
"type": "string",
"example": "Primary intake location for referrals.",
"nullable": true
},
"image": {
"type": "string",
"example": "https://example.com/location.png",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Bulk remove partner locations",
"description": "Delete multiple locations belonging to the specified partner business.",
"operationId": "bulkDeletePartnerLocations",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_ids"
],
"properties": {
"location_ids": {
"description": "IDs of the partner locations to delete",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Locations removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner locations removed successfully"
},
"data": {
"properties": {
"location_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"removed_count": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Validation failed or no partnership"
},
"404": {
"description": "Partner business or locations not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/locations/{location_id}": {
"get": {
"tags": [
"Business Partners"
],
"summary": "Show partner location detail",
"description": "Retrieve a single location belonging to the specified partner business.",
"operationId": "showPartnerLocation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "location_id",
"in": "path",
"description": "Location ID belonging to the partner business",
"required": true,
"schema": {
"type": "integer",
"example": 101
}
}
],
"responses": {
"200": {
"description": "Location retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner location retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or location not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Business Partners"
],
"summary": "Update a partner location",
"description": "Update the details of a partner business location.",
"operationId": "updatePartnerLocation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 45
}
}
],
"requestBody": {
"description": "Updated location details",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Downtown Clinic"
},
"address": {
"type": "string",
"maxLength": 255,
"example": "123 Main Street",
"nullable": true
},
"city": {
"type": "string",
"maxLength": 100,
"example": "Austin",
"nullable": true
},
"state": {
"type": "string",
"maxLength": 100,
"example": "TX",
"nullable": true
},
"country": {
"type": "string",
"maxLength": 100,
"example": "USA",
"nullable": true
},
"phone_number": {
"type": "string",
"maxLength": 50,
"example": "+1 555-0100",
"nullable": true
},
"description": {
"type": "string",
"example": "Primary intake location for referrals.",
"nullable": true
},
"image": {
"type": "string",
"example": "https://example.com/location.png",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Location updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner location updated successfully"
},
"data": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or location not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Remove a partner location",
"description": "Delete a location belonging to the specified partner business.",
"operationId": "deletePartnerLocation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "location_id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 45
}
}
],
"responses": {
"200": {
"description": "Location removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner location removed successfully"
},
"data": {
"properties": {
"location_id": {
"type": "integer",
"example": 45
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or location not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/stations": {
"get": {
"tags": [
"Business Partners"
],
"summary": "List partner stations",
"description": "Retrieve all stations belonging to the specified partner business.",
"operationId": "listPartnerStations",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "search",
"in": "query",
"description": "Filter stations by matching text in the name or description",
"schema": {
"type": "string",
"example": "Consultation"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of stations per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Stations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner stations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetail"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Business Partners"
],
"summary": "Add station to partner's default location",
"description": "Create a station (optionally with services) and attach it to the partner business's default location.",
"operationId": "addStationsToPartner",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"description": "Station details including optional services to create alongside the station.",
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"station": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Station name",
"type": "string",
"example": "Consultation Room 1"
},
"description": {
"description": "Station description",
"type": "string",
"example": "Primary consultation room"
},
"image": {
"description": "Station image URL",
"type": "string",
"example": "https://example.com/station-image.jpg",
"nullable": true
},
"email": {
"description": "Station contact email",
"type": "string",
"format": "email",
"example": "station@example.com",
"nullable": true
},
"services": {
"description": "Services to create and attach to the station",
"type": "array",
"items": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Telehealth Consultation"
},
"description": {
"type": "string",
"example": "30 minute consultation",
"nullable": true
},
"time_in_minute": {
"type": "integer",
"example": 30
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
},
"type": "object"
},
"stations": {
"description": "Optional array for creating multiple stations in one request",
"type": "array",
"items": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Station name",
"type": "string",
"example": "Consultation Room 1"
},
"description": {
"description": "Station description",
"type": "string",
"example": "Primary consultation room",
"nullable": true
},
"image": {
"description": "Station image URL",
"type": "string",
"example": "https://example.com/station-image.jpg",
"nullable": true
},
"email": {
"description": "Station contact email",
"type": "string",
"format": "email",
"example": "station@example.com",
"nullable": true
},
"services": {
"description": "Services to create and attach to the station",
"type": "array",
"items": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Telehealth Consultation"
},
"description": {
"type": "string",
"example": "30 minute consultation",
"nullable": true
},
"time_in_minute": {
"type": "integer",
"example": 30
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Stations added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations added successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Validation failed"
},
"404": {
"description": "Business or partner not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Bulk remove partner stations",
"description": "Delete multiple stations belonging to the specified partner business.",
"operationId": "bulkDeletePartnerStations",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids"
],
"properties": {
"station_ids": {
"description": "IDs of the partner stations to delete",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Stations removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner stations removed successfully"
},
"data": {
"properties": {
"station_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"removed_count": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Validation failed or no partnership"
},
"404": {
"description": "Partner business or stations not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/stations/{station_id}": {
"get": {
"tags": [
"Business Partners"
],
"summary": "Show partner station detail",
"description": "Retrieve a single station belonging to the specified partner business.",
"operationId": "showPartnerStation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID belonging to the partner business",
"required": true,
"schema": {
"type": "integer",
"example": 55
}
}
],
"responses": {
"200": {
"description": "Station retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner station retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/StationDetail"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or station not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Business Partners"
],
"summary": "Update a partner station",
"description": "Update details of a station belonging to the specified partner business.",
"operationId": "updatePartnerStation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 78
}
}
],
"requestBody": {
"description": "Updated station details",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Consultation Room A"
},
"description": {
"type": "string",
"example": "Updated description",
"nullable": true
},
"image": {
"type": "string",
"example": "https://example.com/station.png",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Station updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner station updated successfully"
},
"data": {
"$ref": "#/components/schemas/StationDetail"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or station not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Remove a partner station",
"description": "Delete a station belonging to the specified partner business.",
"operationId": "deletePartnerStation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "station_id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 78
}
}
],
"responses": {
"200": {
"description": "Station removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner station removed successfully"
},
"data": {
"properties": {
"station_id": {
"type": "integer",
"example": 78
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or station not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/services": {
"get": {
"tags": [
"Business Partners"
],
"summary": "List partner services",
"description": "Retrieve all services belonging to the specified partner business.",
"operationId": "listPartnerServices",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "search",
"in": "query",
"description": "Filter services by matching text in the name or description",
"schema": {
"type": "string",
"example": "Consultation"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of services per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner services retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetail"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Business Partners"
],
"summary": "Add services to partner business",
"description": "Create one or multiple services for the partner business",
"operationId": "addServicesToPartner",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"description": "Service(s) details - can be a single service or array of services",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"services"
],
"properties": {
"services": {
"type": "array",
"items": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Service name",
"type": "string",
"example": "General Consultation"
},
"description": {
"description": "Service description",
"type": "string",
"example": "Standard medical consultation"
},
"time_in_minute": {
"description": "Duration in minutes",
"type": "integer",
"example": 30
},
"is_available": {
"description": "Service availability",
"type": "boolean",
"example": true
},
"auto_approve": {
"description": "Auto-approve appointments",
"type": "boolean",
"example": false
},
"is_visible": {
"description": "Service visibility",
"type": "boolean",
"example": true
},
"apply_to_all_locations": {
"description": "If true, service applies to all locations and stations",
"type": "boolean"
},
"location_selections": {
"description": "Applies service to specific locations/stations; optional—omit or pass an empty array to create the service without assigning it to any locations",
"type": "array",
"items": {
"required": [
"location_id"
],
"properties": {
"location_id": {
"type": "integer",
"example": 45
},
"all_stations": {
"description": "Assign to all stations in this location",
"type": "boolean",
"example": true
},
"station_ids": {
"description": "Specific station IDs when all_stations is false",
"type": "array",
"items": {
"type": "integer"
},
"example": [
67,
68
]
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services added successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Validation failed"
},
"404": {
"description": "Business or partner not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Bulk remove partner services",
"description": "Delete multiple services belonging to the specified partner business.",
"operationId": "bulkDeletePartnerServices",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids"
],
"properties": {
"service_ids": {
"description": "IDs of the partner services to delete",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner services removed successfully"
},
"data": {
"properties": {
"service_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"removed_count": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Validation failed or no partnership"
},
"404": {
"description": "Partner business or services not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/services/{service_id}": {
"get": {
"tags": [
"Business Partners"
],
"summary": "Show partner service detail",
"description": "Retrieve a single service belonging to the specified partner business.",
"operationId": "showPartnerService",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "service_id",
"in": "path",
"description": "Service ID belonging to the partner business",
"required": true,
"schema": {
"type": "integer",
"example": 91
}
}
],
"responses": {
"200": {
"description": "Service retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner service retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/ServiceDetail"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or service not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Business Partners"
],
"summary": "Update a partner service",
"description": "Update details of a service belonging to the specified partner business.",
"operationId": "updatePartnerService",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "service_id",
"in": "path",
"description": "Service ID",
"required": true,
"schema": {
"type": "integer",
"example": 91
}
}
],
"requestBody": {
"description": "Updated service details",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "General Consultation"
},
"description": {
"type": "string",
"example": "Updated description",
"nullable": true
},
"time_in_minute": {
"type": "integer",
"example": 45,
"nullable": true
},
"is_available": {
"type": "boolean",
"example": true,
"nullable": true
},
"auto_approve": {
"type": "boolean",
"example": false,
"nullable": true
},
"is_visible": {
"type": "boolean",
"example": true,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Service updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner service updated successfully"
},
"data": {
"$ref": "#/components/schemas/ServiceDetail"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or service not found"
},
"422": {
"description": "Validation failed"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Business Partners"
],
"summary": "Remove a partner service",
"description": "Delete a service belonging to the specified partner business.",
"operationId": "deletePartnerService",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "service_id",
"in": "path",
"description": "Service ID",
"required": true,
"schema": {
"type": "integer",
"example": 91
}
}
],
"responses": {
"200": {
"description": "Service removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner service removed successfully"
},
"data": {
"properties": {
"service_id": {
"type": "integer",
"example": 91
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - No partnership exists"
},
"404": {
"description": "Partner business or service not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/verify-token": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Verify partner invitation token",
"description": "Check if a partner invitation token is valid and not expired",
"operationId": "verifyPartnerToken",
"requestBody": {
"description": "Token verification data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Invitation token to verify",
"type": "string",
"example": "abc123def456..."
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Token is valid",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Token is valid"
},
"data": {
"properties": {
"valid": {
"type": "boolean",
"example": true
},
"partner_business_name": {
"type": "string",
"example": "Partner Medical Clinic"
},
"inviting_business_name": {
"type": "string",
"example": "Main Clinic"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Token is invalid or expired",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid or expired invitation token"
},
"data": {
"properties": {
"valid": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
}
}
},
"/api/v1/partners/activate": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Activate partner account",
"description": "Activate a partner business account and set up password using invitation token",
"operationId": "activatePartner",
"requestBody": {
"description": "Partner activation data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token",
"password"
],
"properties": {
"token": {
"description": "Invitation token",
"type": "string",
"example": "abc123def456..."
},
"password": {
"description": "Password (min 8 characters)",
"type": "string",
"format": "password",
"example": "SecurePass123!"
},
"password_confirmation": {
"description": "Password confirmation",
"type": "string",
"format": "password",
"example": "SecurePass123!"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Partner activated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner account activated successfully"
},
"data": {
"properties": {
"temp_token": {
"description": "Temporary token for automatic login (valid for 10 minutes)",
"type": "string",
"example": "abc123xyz789..."
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Invalid or expired token"
},
"422": {
"description": "Validation error"
}
}
}
},
"/api/v1/partners/{partner_id}/resend-invitation": {
"post": {
"tags": [
"Business Partners"
],
"summary": "Resend partner invitation",
"description": "Resend the activation invitation email to a partner business",
"operationId": "resendPartnerInvitation",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Invitation resent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner invitation resent successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Partner or invitation not found"
},
"400": {
"description": "Partner already activated"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/partners/{partner_id}/status": {
"patch": {
"tags": [
"Business Partners"
],
"summary": "Update partner status",
"description": "Update the partnership status (activate or deactivate)",
"operationId": "updatePartnerStatus",
"parameters": [
{
"name": "partner_id",
"in": "path",
"description": "Partner Business ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"description": "Status update data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"active",
"inactive"
],
"example": "active"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Status updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner status updated successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Partner not found"
},
"400": {
"description": "Bad request - Cannot update pending status"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/simple-data/locations": {
"get": {
"tags": [
"Business Simple Data"
],
"summary": "List simple locations",
"description": "Retrieve lightweight location data for the organization. Supports includes and filters.",
"operationId": "7c27f441592402c9db1918cc4bd291ae",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of includes (stations,address,country,state,image,city,is_active,phone_number,description)",
"required": false,
"schema": {
"type": "string",
"example": "stations,address,city"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by single service ID",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "service_ids",
"in": "query",
"description": "Filter by multiple service IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
5
]
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by single station ID",
"required": false,
"schema": {
"type": "integer",
"example": 12
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter by multiple station IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
12,
18,
25
]
}
},
{
"name": "search",
"in": "query",
"description": "Search by location name",
"required": false,
"schema": {
"type": "string",
"example": "Downtown"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
},
{
"name": "page_limit",
"in": "query",
"description": "Maximum page size",
"required": false,
"schema": {
"type": "integer",
"example": 100
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Location retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BusinessSimpleLocationResource"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/simple-data/providers": {
"get": {
"tags": [
"Business Simple Data"
],
"summary": "List simple providers",
"description": "Retrieve lightweight provider data for the organization. Supports includes and filters.",
"operationId": "e2952d9bd4f71863a233c4c014c07a5a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of includes (stations,image,description,location_id)",
"required": false,
"schema": {
"type": "string",
"example": "image,description"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by single service ID",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "service_ids",
"in": "query",
"description": "Filter by multiple service IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
5
]
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by single location ID",
"required": false,
"schema": {
"type": "integer",
"example": 2
}
},
{
"name": "location_ids",
"in": "query",
"description": "Filter by multiple location IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
2,
3
]
}
},
{
"name": "search",
"in": "query",
"description": "Search by provider name",
"required": false,
"schema": {
"type": "string",
"example": "Smith"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
},
{
"name": "page_limit",
"in": "query",
"description": "Maximum page size",
"required": false,
"schema": {
"type": "integer",
"example": 100
}
}
],
"responses": {
"200": {
"description": "Providers retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BasicProviderResource"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/simple-data/services": {
"get": {
"tags": [
"Business Simple Data"
],
"summary": "List simple services",
"description": "Retrieve lightweight service data for the organization. Supports includes and filters.",
"operationId": "788dd1ef6d6f5e4b4d27c6aec216e096",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of includes (appointment_methods,description,time_in_minute,is_available,auto_approve,is_visible,referral_type)",
"required": false,
"schema": {
"type": "string",
"example": "appointment_methods,description"
}
},
{
"name": "provider_id",
"in": "query",
"description": "Filter by single provider ID",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "provider_ids",
"in": "query",
"description": "Filter by multiple provider IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
10,
11
]
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by single location ID",
"required": false,
"schema": {
"type": "integer",
"example": 2
}
},
{
"name": "location_ids",
"in": "query",
"description": "Filter by multiple location IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
2,
3
]
}
},
{
"name": "referral_type",
"in": "query",
"description": "Filter by referral type",
"required": false,
"schema": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"both"
],
"example": "incoming"
}
},
{
"name": "referral_types",
"in": "query",
"description": "Filter by referral types (comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "incoming,outgoing"
}
},
{
"name": "form_typr",
"in": "query",
"description": "Filter by form type (parameter name is form_typr)",
"required": false,
"schema": {
"type": "string",
"example": "intake"
}
},
{
"name": "search",
"in": "query",
"description": "Search by service name",
"required": false,
"schema": {
"type": "string",
"example": "Consultation"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
},
{
"name": "page_limit",
"in": "query",
"description": "Maximum page size",
"required": false,
"schema": {
"type": "integer",
"example": 100
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BusinessSimpleServiceResource"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/simple-data/users": {
"get": {
"tags": [
"Business Simple Data"
],
"summary": "List simple users",
"description": "Retrieve lightweight user data for the organization. Supports includes and filters.",
"operationId": "968fd58e9d65f53244e752c764245dd9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of includes (phone_number,profile_picture,role)",
"required": false,
"schema": {
"type": "string",
"example": "phone_number,role"
}
},
{
"name": "search",
"in": "query",
"description": "Search by user name or email",
"required": false,
"schema": {
"type": "string",
"example": "alex"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"example": "first_name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
},
{
"name": "page_limit",
"in": "query",
"description": "Maximum page size",
"required": false,
"schema": {
"type": "integer",
"example": 100
}
}
],
"responses": {
"200": {
"description": "Users retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "User retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BusinessSimpleUserResource"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/simple-data/clients": {
"get": {
"tags": [
"Business Simple Data"
],
"summary": "List simple clients",
"description": "Retrieve lightweight client data for the organization. Supports includes and filters.",
"operationId": "67cdb9aaf5bb5da3ea168aeb9c55a9df",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of includes (attributevalues,phone_number,profile_picture_url,is_active,last_visit,priority,external_id)",
"required": false,
"schema": {
"type": "string",
"example": "attributevalues,phone_number"
}
},
{
"name": "search",
"in": "query",
"description": "Search by client name or email",
"required": false,
"schema": {
"type": "string",
"example": "taylor"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"example": "first_name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
},
{
"name": "page_limit",
"in": "query",
"description": "Maximum page size",
"required": false,
"schema": {
"type": "integer",
"example": 100
}
}
],
"responses": {
"200": {
"description": "Clients retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Client retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BusinessSimpleClientResource"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-attributes": {
"get": {
"tags": [
"Client Attributes"
],
"summary": "List patient attributes",
"description": "Get a paginated list of client attributes for the current business.",
"operationId": "6c9a93c286918c57f7f19f3d58bc6318",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search by label or key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by attribute type",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Results per page",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "include_system_fields",
"in": "query",
"description": "Include system fields in results (default: false)",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
}
],
"responses": {
"200": {
"description": "Paginated list of client attributes",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"attributes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientAttributeResource"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Attributes fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Client Attributes"
],
"summary": "Create a new patient attribute",
"description": "Create a new client attribute for the current business.",
"operationId": "ad77c4a4de19c4f8e9bdfd17db9790ad",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreClientAttributeRequest"
}
}
}
},
"responses": {
"201": {
"description": "Client attribute created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientAttributeResource"
},
"message": {
"type": "string",
"example": "Attribute created successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-attributes/{id}": {
"get": {
"tags": [
"Client Attributes"
],
"summary": "Get a patient attribute",
"description": "Retrieve a single client attribute by ID.",
"operationId": "c6b716b64de2300dd4e5eac9a6746def",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Attribute ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Client attribute details",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientAttributeResource"
},
"message": {
"type": "string",
"example": "Attribute retrieved successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Client Attributes"
],
"summary": "Delete a patient attribute",
"description": "Delete a client attribute by ID.",
"operationId": "fb515dffaac1d3478f0ece1ee68721de",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Attribute ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Client attribute deleted",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Attribute deleted successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Not found"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Client Attributes"
],
"summary": "Update a patient attribute (partial update)",
"description": "Partially update an existing client attribute by ID. Only the provided fields will be updated.",
"operationId": "d12d4f655f0aa6222601e40cbf0e99aa",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Attribute ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"label": {
"type": "string",
"example": "Allergies"
},
"type": {
"type": "string",
"example": "text"
},
"is_required": {
"type": "boolean",
"example": false
},
"is_validator": {
"type": "boolean",
"example": false
},
"import_column_name": {
"type": "string",
"example": "Allergies"
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Client attribute updated",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientAttributeResource"
},
"message": {
"type": "string",
"example": "Attribute updated successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Not found"
},
"422": {
"description": "Validation error"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-attributes/conditional": {
"get": {
"tags": [
"Client Attributes"
],
"summary": "Get all attributes (system + custom) for conditional category logic",
"description": "Returns all attributes (system + custom) for the current business, formatted for conditional category logic.",
"operationId": "4af008ebf0ca54e5517207a750b15350",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include_system_fields",
"in": "query",
"description": "Include system fields in results (default: true)",
"required": false,
"schema": {
"type": "boolean",
"example": true
}
}
],
"responses": {
"200": {
"description": "List of attributes for conditional category logic",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Total Spend"
},
"type": {
"type": "string",
"example": "number"
},
"is_system_field": {
"type": "boolean",
"example": true
},
"operators": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "gt"
},
"label": {
"type": "string",
"example": "Greater than"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"message": {
"type": "string",
"example": "Attributes for conditional category fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-attributes/settings": {
"get": {
"tags": [
"Patient Attribute Settings"
],
"summary": "List patient attributes for settings",
"description": "Get a simple list of all client attributes for the current business with their configurations and options.",
"operationId": "a7337f8f7175d200d83b59d17c76a2e3",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "List of client attributes",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"message": {
"type": "string",
"example": "Attributes fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "An error occurred"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-attributes/type-configs": {
"get": {
"tags": [
"Patient Attribute Settings"
],
"summary": "Get attribute type configurations",
"description": "Retrieves all available attribute types and their configuration options.",
"operationId": "a119b5817b11a29227e312b0a102e686",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Attribute type configurations",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"message": {
"type": "string",
"example": "Attributes type configuration fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "An error occurred"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-attributes/update-all": {
"post": {
"tags": [
"Patient Attribute Settings"
],
"summary": "Bulk update patient attributes",
"description": "Updates the configuration of client attributes. Supports creating new attributes, updating existing ones, and removing attributes (with restrictions for system fields).",
"operationId": "1fab426ce61eb2aa989d83d1e1836b50",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientAttributeSettingRequest"
}
}
}
},
"responses": {
"200": {
"description": "Attributes updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"message": {
"type": "string",
"example": "Attributes updated successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Processing failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Processing failed"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "An error occurred"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories": {
"get": {
"tags": [
"Client Categories"
],
"summary": "List patient categories",
"operationId": "705260328a578bceb378b7f1d5a81c29",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "ids",
"in": "query",
"description": "Filter by client category IDs (comma-separated)",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"description": "Search in name and description",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "location",
"in": "query",
"description": "Comma-separated location IDs",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "station",
"in": "query",
"description": "Comma-separated station IDs",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "location_id",
"in": "query",
"description": "Single location ID (legacy)",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "query",
"description": "Single station ID (legacy)",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "include_locations",
"in": "query",
"description": "Include location details",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "include_stations",
"in": "query",
"description": "Include station details",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "include_location_selections",
"in": "query",
"description": "Include location selections",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field (name, description, type, created_at, updated_at)",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (asc, desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientCategoryResource"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Client Categories"
],
"summary": "Create a new patient category",
"description": "Create a new client category with support for both manual and conditional types. Conditional categories use multiple conditions with AND logic.",
"operationId": "955feb42e140857d0e1f272384416919",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Category name",
"type": "string",
"example": "VIP Clients"
},
"description": {
"description": "Category description",
"type": "string",
"example": "High-value clients"
},
"color": {
"description": "Category color in hex format",
"type": "string",
"example": "#FF5733"
},
"type": {
"description": "Category type - manual for direct assignment, conditional for rule-based assignment",
"type": "string",
"enum": [
"manual",
"conditional"
],
"example": "conditional"
},
"conditions": {
"description": "Array of conditions for conditional categories. All conditions must match (AND logic).",
"type": "array",
"items": {
"properties": {
"condition_type": {
"description": "Type of condition",
"type": "string",
"enum": [
"priority",
"registration_date",
"last_visit",
"information_check"
],
"example": "priority"
},
"operator": {
"description": "Operator for the condition. For priority conditions, defaults to 'equals' if not provided.",
"type": "string",
"example": "equals"
},
"conditional_value": {
"description": "Value to compare against",
"type": "string",
"example": "high"
},
"date_range_start": {
"description": "Start date for date range conditions",
"type": "string",
"format": "date",
"example": "2024-01-01"
},
"date_range_end": {
"description": "End date for date range conditions",
"type": "string",
"format": "date",
"example": "2024-12-31"
},
"information_type": {
"description": "Type of information check (only for information_check condition_type)",
"type": "string",
"enum": [
"form_answer",
"custom_intake_answer"
],
"example": "form_answer"
},
"form_question_id": {
"description": "Form question UUID (only for form_answer information_type)",
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"custom_intake_id": {
"description": "Custom intake ID (only for custom_intake_answer information_type)",
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"client_ids": {
"description": "Array of client IDs for manual assignment (manual categories only)",
"type": "array",
"items": {
"type": "integer"
}
},
"station_ids": {
"description": "Array of station IDs for manual assignment (manual categories only)",
"type": "array",
"items": {
"type": "integer"
}
},
"location_ids": {
"description": "Array of location IDs for manual assignment (manual categories only)",
"type": "array",
"items": {
"type": "integer"
}
},
"location_selections": {
"description": "Advanced location and station selection (manual categories only)",
"type": "array",
"items": {
"properties": {
"location_id": {
"description": "Location ID",
"type": "integer",
"example": 1
},
"all_stations": {
"description": "Include all stations in this location",
"type": "boolean",
"example": true
},
"station_ids": {
"description": "Specific station IDs to include",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Category created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientCategoryResource"
},
"message": {
"type": "string",
"example": "Category created successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot assign stations/locations to conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}": {
"get": {
"tags": [
"Client Categories"
],
"summary": "Get a patient category",
"operationId": "078a2ff637bac43bdcbbdd09e667d386",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientCategoryResource"
},
"message": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Client Categories"
],
"summary": "Delete a patient category",
"operationId": "de90e74202b6d5fccafbcc9b16b3d8b6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Deleted",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Category deleted successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Client Categories"
],
"summary": "Update a patient category (full or partial update)",
"operationId": "1f582b35b5e97b40929e29f122dfa38f",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateClientCategoryRequest"
}
}
}
},
"responses": {
"200": {
"description": "Category updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientCategoryResource"
},
"message": {
"type": "string",
"example": "Category updated successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Category not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Category not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}/clients": {
"get": {
"tags": [
"Client Categories"
],
"summary": "Get paginated patients for a category",
"operationId": "377d42712d0c58980d5c28436aa19cec",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BasicClientResource"
}
},
"meta": {
"type": "object"
},
"message": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Category not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Client Categories"
],
"summary": "Attach patients to a category",
"operationId": "02cc1468aab6ffa4b63c851fc2e9783d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_ids"
],
"properties": {
"client_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patients attached successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Client Categories"
],
"summary": "Detach patients from a category",
"operationId": "943708f7b400c7f4b005d733ee7d314b",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_ids"
],
"properties": {
"client_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patients detached successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Client Categories"
],
"summary": "Sync patients for a category",
"operationId": "f419914081f0f54cbb77ec4ff0d667c2",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_ids"
],
"properties": {
"client_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patients synced successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}/stations": {
"get": {
"tags": [
"Client Categories"
],
"summary": "Get paginated stations for a category",
"operationId": "179fd538f3dea36c1f75b096de87009f",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SimpleWorkspaceInfoResource"
}
},
"meta": {
"type": "object"
},
"message": {
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Client Categories"
],
"summary": "Attach stations to a category",
"description": "Attach stations to a manual category. This operation is not supported for conditional categories.",
"operationId": "6bdb5612226c04bac86713ad242d1594",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids"
],
"properties": {
"station_ids": {
"description": "Array of station IDs to attach",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations attached successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot attach stations to conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Client Categories"
],
"summary": "Detach stations from a category",
"description": "Detach stations from a manual category. This operation is not supported for conditional categories.",
"operationId": "58956cc08d4b4fb3518b6adc629e8785",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids"
],
"properties": {
"station_ids": {
"description": "Array of station IDs to detach",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations detached successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot detach stations from conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Client Categories"
],
"summary": "Sync stations for a category",
"description": "Replace all station assignments for a manual category. This operation is not supported for conditional categories.",
"operationId": "9c7830d6111e8c9fa98566430992f864",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids"
],
"properties": {
"station_ids": {
"description": "Array of station IDs to sync",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations synced successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot sync stations for conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}/locations": {
"get": {
"tags": [
"Client Categories"
],
"summary": "Get paginated locations for a category",
"operationId": "5b27fcbe557845900c8367d69759bcd6",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SimpleWorkspaceInfoResource"
}
},
"meta": {
"type": "object"
},
"message": {
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Client Categories"
],
"summary": "Attach locations to a category",
"description": "Attach locations to a manual category. This operation is not supported for conditional categories.",
"operationId": "3b68356f4d585dafcb320f27e472c2b9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_ids"
],
"properties": {
"location_ids": {
"description": "Array of location IDs to attach",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations attached successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot attach locations to conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Client Categories"
],
"summary": "Detach locations from a category",
"description": "Detach locations from a manual category. This operation is not supported for conditional categories.",
"operationId": "57d484c62ba2ca6de97fa44477b302d1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_ids"
],
"properties": {
"location_ids": {
"description": "Array of location IDs to detach",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations detached successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot detach locations from conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Client Categories"
],
"summary": "Sync locations for a category",
"description": "Replace all location assignments for a manual category. This operation is not supported for conditional categories.",
"operationId": "1212c283bcc771501ee6bc06e17e8fc5",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_ids"
],
"properties": {
"location_ids": {
"description": "Array of location IDs to sync",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations synced successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot sync locations for conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}/info": {
"patch": {
"tags": [
"Client Categories"
],
"summary": "Update category info (name, description, color, type)",
"operationId": "181c620109cb2fe3c4cdabc8b543c6eb",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"color": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"manual",
"conditional"
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientCategoryResource"
},
"message": {
"type": "string",
"example": "Category info updated successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}/conditions": {
"patch": {
"tags": [
"Client Categories"
],
"summary": "Update category conditions",
"description": "Update conditions for a conditional category. This replaces all existing conditions with the new set. All conditions must match (AND logic).",
"operationId": "bd932851af5b66397f1307f57053a5ca",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"conditions"
],
"properties": {
"conditions": {
"description": "Array of conditions. All conditions must match (AND logic).",
"type": "array",
"items": {
"properties": {
"condition_type": {
"description": "Type of condition",
"type": "string",
"enum": [
"priority",
"registration_date",
"last_visit",
"information_check"
],
"example": "priority"
},
"operator": {
"description": "Operator for the condition. For priority conditions, defaults to 'equals' if not provided.",
"type": "string",
"example": "equals"
},
"conditional_value": {
"description": "Value to compare against",
"type": "string",
"example": "high"
},
"date_range_start": {
"description": "Start date for date range conditions",
"type": "string",
"format": "date",
"example": "2024-01-01"
},
"date_range_end": {
"description": "End date for date range conditions",
"type": "string",
"format": "date",
"example": "2024-12-31"
},
"information_type": {
"description": "Type of information check (only for information_check condition_type)",
"type": "string",
"enum": [
"form_answer",
"custom_intake_answer"
],
"example": "form_answer"
},
"form_question_id": {
"description": "Form question UUID (only for form_answer information_type)",
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"custom_intake_id": {
"description": "Custom intake ID (only for custom_intake_answer information_type)",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Conditions updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ClientCategoryResource"
},
"message": {
"type": "string",
"example": "Category conditions updated successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"404": {
"description": "Category not found"
},
"403": {
"description": "Forbidden - category is not conditional type"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/{id}/sync": {
"patch": {
"tags": [
"Client Categories"
],
"summary": "Sync category relations (patients, stations, locations)",
"description": "Sync relations for a category. Client operations work for both manual and conditional categories. Station and location operations are manual-only and not supported for conditional categories.",
"operationId": "36027611a5a3f4711c1cd3a2e6901963",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Category ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"client_ids": {
"description": "Array of client IDs to sync (works for both manual and conditional categories)",
"type": "array",
"items": {
"type": "integer"
}
},
"station_ids": {
"description": "Array of station IDs to sync (manual categories only)",
"type": "array",
"items": {
"type": "integer"
}
},
"location_ids": {
"description": "Array of location IDs to sync (manual categories only)",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Category relations synced successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"403": {
"description": "Forbidden - cannot sync stations/locations for conditional categories"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/get-forms-for-conditional": {
"get": {
"tags": [
"Conditional Forms"
],
"summary": "Get forms with flattened fields for conditional logic",
"operationId": "0c8d08a365e74cf1cf4401b898d626c1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FormForConditional"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-categories/get-custom-intakes-for-conditional": {
"get": {
"tags": [
"Conditional Category Configs"
],
"summary": "Get custom intakes for conditional logic",
"operationId": "fde23072949335fcb51ebc7598522f5a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomIntakeForConditional"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Business not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients": {
"get": {
"tags": [
"Clients"
],
"summary": "List patients",
"operationId": "c0c485b375237d5b671db90982e44dfb",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search in first name, last name, email, and phone number",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "phone_number",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "emr_sync_status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"synched",
"sync_failed",
"sync_in_progress"
]
}
},
{
"name": "last_visit_start",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "last_visit_end",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field (first_name, last_name, email, phone_number, created_at, updated_at)",
"required": false,
"schema": {
"type": "string",
"example": "first_name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (asc, desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer",
"example": 20
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BasicClientResource"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Clients"
],
"summary": "Create a patient",
"operationId": "697c83d35a3801c641f42058c0e51557",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"first_name",
"last_name",
"phone_number"
],
"properties": {
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"attribute_values": {
"description": "Key-value pairs for custom attributes",
"type": "object",
"example": {
"allergies": "Peanuts",
"preferred_language": "English"
},
"additionalProperties": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetailedClientResource"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/{id}": {
"get": {
"tags": [
"Clients"
],
"summary": "Get patient details",
"description": "Get detailed information about a specific client. Use the include parameter to load related data.",
"operationId": "4f79664822960d8d897c36d2d18b39d2",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of relationships to include (e.g., categories)",
"required": false,
"schema": {
"type": "string",
"example": "categories"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetailedClientResource"
}
}
}
},
"404": {
"description": "Patient not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Clients"
],
"summary": "Update a patient (full update)",
"operationId": "9a8a93178cc42b13ccbe2cb84aa53603",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"attribute_values": {
"description": "Key-value pairs for custom attributes",
"type": "object",
"example": {
"allergies": "Peanuts",
"preferred_language": "English"
},
"additionalProperties": {
"type": "string"
}
},
"attach_categories": {
"description": "Category IDs to attach",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
},
"detach_categories": {
"description": "Category IDs to detach",
"type": "array",
"items": {
"type": "integer"
},
"example": [
3
]
},
"sync_categories": {
"description": "Category IDs to sync (replace all manual categories)",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetailedClientResource"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Clients"
],
"summary": "Delete a patient",
"operationId": "59f79f2507036e733b6514676c895b70",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Deleted"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Clients"
],
"summary": "Partial update of a patient",
"description": "Update only the specified fields of a client. Supports basic info, attributes, and category management.",
"operationId": "93c618e97025326a525efe71a4e00c2c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"first_name": {
"description": "Optional: Update first name",
"type": "string",
"example": "John"
},
"last_name": {
"description": "Optional: Update last name",
"type": "string",
"example": "Doe"
},
"email": {
"description": "Optional: Update email",
"type": "string",
"example": "john.doe@example.com"
},
"phone_number": {
"description": "Optional: Update phone number",
"type": "string",
"example": "+1234567890"
},
"is_active": {
"description": "Optional: Update active status",
"type": "boolean",
"example": true
},
"attribute_values": {
"description": "Optional: Update specific custom attributes",
"type": "object",
"example": {
"allergies": "Peanuts",
"preferred_language": "English"
},
"additionalProperties": {
"type": "string"
}
},
"attach_categories": {
"description": "Optional: Category IDs to attach to client",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
},
"detach_categories": {
"description": "Optional: Category IDs to detach from client",
"type": "array",
"items": {
"type": "integer"
},
"example": [
3
]
},
"sync_categories": {
"description": "Optional: Replace all manual categories with these IDs",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Partial update successful",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient updated successfully"
},
"data": {
"$ref": "#/components/schemas/DetailedClientResource"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Patient not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/{id}/form-responses": {
"get": {
"tags": [
"Clients"
],
"summary": "Get patient form responses",
"operationId": "ce77b4523cb950674ec07cd751855c8e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientFormResponseResource"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/{id}/intakes": {
"get": {
"tags": [
"Clients"
],
"summary": "Get patient custom intake responses",
"description": "Retrieve all custom intake responses for a specific client. This endpoint allows business users to view client intake form responses.",
"operationId": "6c135928f0ddf15cc3ffd90b2db24c48",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Client ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "intake_id",
"in": "query",
"description": "Filter by specific intake field ID",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter responses from this date",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter responses until this date",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "value",
"in": "query",
"description": "Search in response values",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Client intake responses retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake responses retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientIntakeResponseResource"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Clients"
],
"summary": "Update patient custom intake responses",
"description": "Update or create custom intake responses for a specific client. This endpoint allows business users to directly manage client intake form responses.",
"operationId": "94b1ca11716546c420f2b8436178ff44",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Client ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"intakes"
],
"properties": {
"intakes": {
"description": "Array of intake responses to update or create",
"type": "array",
"items": {
"required": [
"intake_id",
"value"
],
"properties": {
"intake_id": {
"description": "ID of the custom intake field",
"type": "integer",
"example": 1
},
"value": {
"description": "Response value (can be JSON for multi-select fields)",
"type": "string",
"example": "option_value"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Intake responses updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake responses updated successfully"
},
"data": {
"properties": {
"updated_count": {
"description": "Number of intake responses updated",
"type": "integer",
"example": 3
},
"responses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientIntakeResponseResource"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request - Invalid client or business mismatch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"401": {
"description": "Unauthorized - Client does not belong to business",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"422": {
"description": "Validation failed - Invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/statuses": {
"get": {
"tags": [
"Clients"
],
"summary": "Get patient status list",
"description": "Retrieve a list of all available client statuses",
"operationId": "d86006b6a33239aec0cdca8c27e83f9a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "active"
},
"name": {
"type": "string",
"example": "Active"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/bulk-message": {
"post": {
"tags": [
"Clients"
],
"summary": "Send bulk messages to multiple patients",
"description": "Create a bulk message request and send messages to multiple clients via email and/or SMS. You can target clients by specific IDs or by client category.",
"operationId": "41fb1d9c13980c90c4fcf13a5e310646",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"message",
"send_via_email",
"send_via_sms"
],
"properties": {
"message": {
"description": "The message content to send to clients",
"type": "string",
"maxLength": 1000,
"example": "Thank you for choosing our services! We have a special offer for you."
},
"send_via_email": {
"description": "Whether to send the message via email",
"type": "boolean",
"example": true
},
"send_via_sms": {
"description": "Whether to send the message via SMS",
"type": "boolean",
"example": false
},
"client_category_id": {
"description": "ID of the client category to send messages to. If provided, client_ids is not required.",
"type": "integer",
"example": 123,
"nullable": true
},
"client_ids": {
"description": "Array of specific client IDs to send messages to. Required if client_category_id is not provided.",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
],
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Bulk message sent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient Bulk Message created successfully"
},
"data": {
"properties": {
"client_count": {
"description": "Total number of clients targeted",
"type": "integer",
"example": 25
},
"email_sent": {
"description": "Number of emails successfully sent",
"type": "integer",
"example": 20
},
"sms_sent": {
"description": "Number of SMS messages successfully sent",
"type": "integer",
"example": 18
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request - Validation failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"data": {
"properties": {
"errors": {
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Unprocessable Entity - Validation errors",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to create bulk message"
},
"data": {
"type": "array",
"items": {
"type": "string",
"example": "Database connection failed"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/bulk-delete": {
"post": {
"tags": [
"Clients"
],
"summary": "Bulk delete patients",
"description": "Delete multiple clients by their IDs",
"operationId": "c6bb1e3539385b7dba9ab69e3f60aebe",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_ids"
],
"properties": {
"client_ids": {
"description": "Array of client IDs to delete",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Clients deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 patients deleted successfully!"
},
"data": {
"properties": {
"deleted_count": {
"type": "integer",
"example": 5
},
"not_found_count": {
"type": "integer",
"example": 0
},
"deleted_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"not_found_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/bulk-update-status": {
"post": {
"tags": [
"Clients"
],
"summary": "Bulk update patient status",
"description": "Update the active status for multiple clients",
"operationId": "0878d714d016dc988c9fcb3e0737b351",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_ids",
"is_active"
],
"properties": {
"client_ids": {
"description": "Array of client IDs to update",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"is_active": {
"description": "Active status to set",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Client statuses updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 patients updated successfully!"
},
"data": {
"properties": {
"updated_count": {
"type": "integer",
"example": 5
},
"not_found_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/bulk-assign-categories": {
"post": {
"tags": [
"Clients"
],
"summary": "Bulk assign patients to categories",
"description": "Assign multiple clients to one or more categories",
"operationId": "db3284d8503b8dfa45eb53ca8226fc8c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_ids",
"category_ids"
],
"properties": {
"client_ids": {
"description": "Array of client IDs to assign",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"category_ids": {
"description": "Array of category IDs to assign to",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"replace": {
"description": "Whether to replace existing categories or add to them",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Categories assigned successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Categories assigned to 5 patients successfully!"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-import/attributes": {
"get": {
"tags": [
"Client Import"
],
"summary": "Get attributes for patient import",
"description": "Retrieve all patient attributes that can be used for patient import, including system fields",
"operationId": "9269662ba5be033ecb3587362727e6a9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Attributes fetched successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientAttributeForClientImportResource"
}
},
"message": {
"type": "string",
"example": "Attributes fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-import/validate-attribute-sync": {
"post": {
"tags": [
"Client Import"
],
"summary": "Validate attribute sync for import",
"description": "Validate attribute data before syncing for patient import",
"operationId": "3bb787318eaf31a396e8421018f9db61",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Attribute data to validate",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttributeSyncForImportRequest"
}
}
}
},
"responses": {
"200": {
"description": "Data is correct and ready to be processed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "null",
"example": null
},
"message": {
"type": "string",
"example": "Data is Correct and ready to be processed"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation errors",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-import/sync-attributes": {
"post": {
"tags": [
"Client Import"
],
"summary": "Sync patient attributes",
"description": "Update multiple patient attributes in a single request. Handles both system and custom attributes.",
"operationId": "582796926b49e9480e8be923c22db50a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Array of attribute objects to update",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"required": [
"label",
"type",
"import_column_name"
],
"properties": {
"label": {
"type": "string",
"maxLength": 255,
"example": "First Name"
},
"type": {
"type": "string",
"enum": [
"text",
"number",
"date",
"select",
"boolean",
"email",
"phone",
"attachment"
],
"example": "text"
},
"is_validator": {
"type": "boolean",
"example": false
},
"import_column_name": {
"type": "string",
"maxLength": 255,
"example": "first_name"
}
},
"type": "object"
}
},
"example": [
{
"label": "First Name",
"type": "text",
"is_validator": false,
"import_column_name": "first_name"
},
{
"label": "Last Visit Date",
"type": "date",
"is_validator": true,
"import_column_name": "last_visit"
}
]
}
}
},
"responses": {
"200": {
"description": "Attributes processed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientAttributeResource"
}
},
"message": {
"type": "string",
"example": "Attributes processed successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation errors",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Processing failed: Validation error"
},
"errors": {
"type": "object",
"example": {
"label": [
"The label field is required."
],
"type": [
"The selected type is invalid."
]
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Processing failed: Database error"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-import/validate-import": {
"post": {
"tags": [
"Client Import"
],
"summary": "Validate patient import data",
"description": "Validate patient import data without processing the import",
"operationId": "33cb27087466f5a6c06ff21feb681578",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Array of patient data to validate",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"description": "Patient data object",
"properties": {
"external_id": {
"type": "string",
"example": "EXT001",
"nullable": true
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"date_of_birth": {
"type": "string",
"format": "date",
"example": "1990-01-01"
},
"is_active": {
"type": "boolean",
"example": true
},
"priority": {
"type": "string",
"example": "high"
},
"attributes": {
"description": "Custom attribute values",
"type": "object",
"additionalProperties": {
"type": "string",
"example": "Peanut allergy"
}
}
},
"type": "object"
}
},
"example": [
{
"external_id": "EXT001",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+1234567890",
"date_of_birth": "1990-01-01",
"is_active": true,
"priority": "high",
"allergies": "Peanut allergy",
"emergency_contact": "Jane Doe"
}
]
}
}
},
"responses": {
"200": {
"description": "Validation completed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"valid": {
"type": "array",
"items": {
"type": "object"
}
},
"invalid": {
"type": "array",
"items": {
"type": "object"
}
},
"summary": {
"properties": {
"total": {
"type": "integer",
"example": 1
},
"valid": {
"type": "integer",
"example": 1
},
"invalid": {
"type": "integer",
"example": 0
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
},
"validation_rules": {
"type": "object"
},
"attribute_mapping": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Validation completed"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation errors",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-import/bulk-import": {
"post": {
"tags": [
"Client Import"
],
"summary": "Bulk import patients with validation",
"description": "Import multiple patients in bulk with comprehensive validation",
"operationId": "c0e88be6460900463448587d9a6b52b4",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Array of patient data to import",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"description": "Patient data object",
"properties": {
"external_id": {
"type": "string",
"example": "EXT001",
"nullable": true
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"date_of_birth": {
"type": "string",
"format": "date",
"example": "1990-01-01"
},
"is_active": {
"type": "boolean",
"example": true
},
"priority": {
"type": "string",
"example": "high"
},
"attributes": {
"description": "Custom attribute values",
"type": "object",
"additionalProperties": {
"type": "string",
"example": "Peanut allergy"
}
}
},
"type": "object"
}
},
"example": [
{
"external_id": "EXT001",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+1234567890",
"date_of_birth": "1990-01-01",
"is_active": true,
"priority": "high",
"allergies": "Peanut allergy",
"emergency_contact": "Jane Doe"
}
]
}
}
},
"responses": {
"201": {
"description": "Patients imported successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"import_result": {
"type": "object"
},
"validation_result": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Import completed successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation errors",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Import validation failed"
},
"validation_result": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Import failed: Database error"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/download-sample-csv": {
"get": {
"tags": [
"Clients"
],
"summary": "Download sample CSV for patient import",
"description": "Downloads a sample CSV file with headers and sample data for patient import",
"operationId": "0f6044b7a75546df493a88b47e7f3e95",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "CSV file download",
"headers": {
"Content-Disposition": {
"description": "Attachment filename",
"schema": {
"type": "string",
"example": "attachment; filename=client_import_sample.csv"
}
},
"Content-Type": {
"description": "CSV content type",
"schema": {
"type": "string",
"example": "text/csv"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/export": {
"get": {
"tags": [
"Clients"
],
"summary": "Export all patients to CSV",
"description": "Exports all patients with their attributes to a CSV file for download",
"operationId": "56568709d5735d75f4289a6b0ea92956",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "CSV file download",
"headers": {
"Content-Disposition": {
"description": "Attachment filename",
"schema": {
"type": "string",
"example": "attachment; filename=clients_export.csv"
}
},
"Content-Type": {
"description": "CSV content type",
"schema": {
"type": "string",
"example": "text/csv"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/table-settings/available-columns": {
"get": {
"tags": [
"Client Table Settings"
],
"summary": "Get available columns for client table",
"description": "Returns a list of all available columns that can be displayed in the client table, along with their metadata.",
"operationId": "a5ed4cef434b39f4ada4062fbe131560",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Available columns retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Available columns retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "external_id"
},
"label": {
"type": "string",
"example": "Patient ID"
},
"description": {
"type": "string",
"example": "Unique patient identifier"
},
"default_visible": {
"type": "boolean",
"example": true
},
"default_order": {
"type": "integer",
"example": 1
},
"sortable": {
"type": "boolean",
"example": true
},
"type": {
"type": "string",
"example": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/clients/table-settings": {
"get": {
"tags": [
"Client Table Settings"
],
"summary": "Get business's client table column settings",
"description": "Returns the business's saved column configuration for the client table, including which columns are visible and their order.",
"operationId": "6c2be6ccd5baeeb4a15f9cdea5db9a14",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Column settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Column settings retrieved successfully"
},
"data": {
"properties": {
"columns": {
"description": "Array of column configurations in display order",
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "external_id"
},
"visible": {
"type": "boolean",
"example": true
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"available_columns": {
"description": "All available columns with metadata",
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "external_id"
},
"label": {
"type": "string",
"example": "Patient ID"
},
"description": {
"type": "string",
"example": "Unique patient identifier"
},
"default_visible": {
"type": "boolean",
"example": true
},
"default_order": {
"type": "integer",
"example": 1
},
"sortable": {
"type": "boolean",
"example": true
},
"type": {
"type": "string",
"example": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Client Table Settings"
],
"summary": "Save business's client table column settings",
"description": "Saves the business's column configuration for the client table, including which columns are visible and their order. This setting applies to all users in the organization.",
"operationId": "fc1bb6f82b6eaebdab9e75ee1489e4cd",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"columns"
],
"properties": {
"columns": {
"description": "Array of column configurations in display order",
"type": "array",
"items": {
"required": [
"key",
"visible",
"order"
],
"properties": {
"key": {
"description": "Column identifier",
"type": "string",
"example": "external_id"
},
"visible": {
"description": "Whether column is visible",
"type": "boolean",
"example": true
},
"order": {
"description": "Display order (1-based)",
"type": "integer",
"example": 1
}
},
"type": "object"
},
"example": [
{
"key": "external_id",
"visible": true,
"order": 1
},
{
"key": "full_name",
"visible": true,
"order": 2
},
{
"key": "email",
"visible": true,
"order": 3
},
{
"key": "phone_number",
"visible": true,
"order": 4
},
{
"key": "is_active",
"visible": true,
"order": 5
},
{
"key": "last_visit",
"visible": false,
"order": 6
}
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Column settings saved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Column settings saved successfully"
},
"data": {
"properties": {
"columns": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string"
},
"visible": {
"type": "boolean"
},
"order": {
"type": "integer"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Client Table Settings"
],
"summary": "Reset client table column settings to default",
"description": "Resets the business's column configuration for the client table to the default settings.",
"operationId": "afb160c0823f36a9b8b55c01c4c784b9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Column settings reset successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Column settings reset to default"
},
"data": {
"properties": {
"columns": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string"
},
"visible": {
"type": "boolean"
},
"order": {
"type": "integer"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/custom-intakes": {
"get": {
"tags": [
"Custom Intakes"
],
"summary": "List intake fields",
"description": "Get a paginated list of intake fields for the current business, optionally filtered by location and/or station",
"operationId": "getCustomIntakes",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to filter intakes by location",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to filter intakes by station",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "search",
"in": "query",
"description": "Search term to filter by name or key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by field type",
"required": false,
"schema": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
]
}
},
{
"name": "is_visible",
"in": "query",
"description": "Filter by visibility status",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"description": "Items per page (default: 15)",
"required": false,
"schema": {
"type": "integer",
"default": 15
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field (name, key, type, order, created_at, updated_at)",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (asc, desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"intakes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntakeResourceForList"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Custom intakes retrieved successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Custom Intakes"
],
"summary": "Create a new intake field",
"description": "Create a new intake field for the current business, optionally associated with a specific location and/or station. Field names must be unique within the specified context (business/location/station).",
"operationId": "createCustomIntake",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to associate the intake with a specific location",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to associate the intake with a specific station",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreCustomIntakeRequest"
}
}
}
},
"responses": {
"201": {
"description": "Intake field created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"intake": {
"$ref": "#/components/schemas/IntakeDetailResource"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Intake created successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/custom-intakes/others": {
"get": {
"tags": [
"Custom Intakes"
],
"summary": "List others intake fields",
"description": "Get a paginated list of others intake fields for the current business, optionally filtered by location and/or station",
"operationId": "f2506fd606aa839b518e6c1287461ae7",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to filter intakes by location",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to filter intakes by station",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "search",
"in": "query",
"description": "Search term to filter by name or key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by field type",
"required": false,
"schema": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
]
}
},
{
"name": "is_visible",
"in": "query",
"description": "Filter by visibility status",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"description": "Items per page (default: 15)",
"required": false,
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"intakes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntakeResourceForList"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Others intakes retrieved successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/custom-intakes/{customIntake}": {
"get": {
"tags": [
"Custom Intakes"
],
"summary": "Get intake field details",
"description": "Get detailed information about a specific intake field, optionally filtered by location and/or station context",
"operationId": "1127e963ebf595b743a81e935714b8e4",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to filter by location context",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to filter by station context",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "customIntake",
"in": "path",
"description": "Intake field ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Intake field details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"intake": {
"$ref": "#/components/schemas/IntakeDetailResource"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Intake retrieved successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Intake not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Custom Intakes"
],
"summary": "Update an intake field",
"description": "Update an existing intake field, optionally filtered by location and/or station context. Field names must be unique within the specified context (business/location/station).",
"operationId": "8c11772172e645cf858f24515f7a7b9d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to filter by location context",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to filter by station context",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "customIntake",
"in": "path",
"description": "Intake field ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCustomIntakeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Intake field updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"intake": {
"$ref": "#/components/schemas/IntakeDetailResource"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Intake updated successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"404": {
"description": "Intake not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Custom Intakes"
],
"summary": "Delete an intake field",
"description": "Delete an intake field, optionally filtered by location and/or station context",
"operationId": "70331eba58b8f549d5b12f022086fe6a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to filter by location context",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to filter by station context",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "customIntake",
"in": "path",
"description": "Intake field ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Intake field deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Intake deleted successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Intake not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/custom-intakes/bulk-update": {
"post": {
"tags": [
"Custom Intakes"
],
"summary": "Bulk update intake fields",
"description": "Bulk create, update, or delete intake fields for the current business, optionally filtered by location and/or station context",
"operationId": "7ead8557a56653f20e4244ef5268aaf2",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional location ID to filter by location context",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional station ID to filter by station context",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkSyncCustomIntakesRequest"
}
}
}
},
"responses": {
"200": {
"description": "Bulk sync completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"created": {
"type": "integer",
"example": 5
},
"updated": {
"type": "integer",
"example": 3
},
"deleted": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Bulk sync completed successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/analytics/overall-ratings": {
"get": {
"tags": [
"Patient Experience Analytics"
],
"summary": "Get overall ratings statistics",
"description": "Retrieve overall statistics for patient experience ratings including average rating and total reviews",
"operationId": "c291e4f4c8d4baa36cfdfe8c0d8ff248",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by start date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by end date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "statuses[]",
"in": "query",
"description": "Filter by appointment types (walk-in or scheduled)",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"walk-in",
"scheduled"
]
},
"example": [
"walk-in",
"scheduled"
]
}
},
{
"name": "location_ids[]",
"in": "query",
"description": "Filter by location IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
{
"name": "station_ids[]",
"in": "query",
"description": "Filter by station IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
{
"name": "service_ids[]",
"in": "query",
"description": "Filter by service IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
{
"name": "category_ids[]",
"in": "query",
"description": "Filter by client category IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"average": {
"description": "Overall average rating on 1-5 scale",
"type": "number",
"format": "float",
"example": 2.4
},
"total_reviews": {
"description": "Total number of responses with ratings",
"type": "integer",
"example": 23
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Overall ratings fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/analytics/rating": {
"get": {
"tags": [
"Patient Experience Analytics"
],
"summary": "Get grouped ratings analytics",
"description": "Retrieve comprehensive ratings analytics data broken down by location, station, service type, and client category. Each group contains aggregated data across all entities in that dimension.",
"operationId": "1de6506dfd4354ff804e3ad0b0bbf812",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by start date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by end date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "statuses[]",
"in": "query",
"description": "Filter by appointment types (walk-in or scheduled)",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"walk-in",
"scheduled"
]
},
"example": [
"walk-in",
"scheduled"
]
}
},
{
"name": "location_ids[]",
"in": "query",
"description": "Filter by location IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
{
"name": "station_ids[]",
"in": "query",
"description": "Filter by station IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
{
"name": "service_ids[]",
"in": "query",
"description": "Filter by service IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
{
"name": "category_ids[]",
"in": "query",
"description": "Filter by client category IDs",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Grouped ratings fetched successfully"
},
"data": {
"properties": {
"summary": {
"description": "Overall summary statistics",
"properties": {
"total_reviews": {
"description": "Total number of reviews",
"type": "integer",
"example": 150
},
"average": {
"description": "Overall average rating on 1-5 scale",
"type": "number",
"format": "float",
"example": 4.2
}
},
"type": "object"
},
"charts": {
"description": "Detailed analytics breakdown by dimensions",
"properties": {
"by_locations": {
"description": "Aggregated ratings data across all locations",
"properties": {
"average_participants": {
"description": "Average participation percentage across all locations",
"type": "number",
"format": "float",
"example": 85.5
},
"total_reviews": {
"description": "Total reviews across all locations",
"type": "integer",
"example": 45
},
"average": {
"description": "Average rating across all locations",
"type": "number",
"format": "float",
"example": 4.1
},
"distribution": {
"description": "Aggregated rating distribution across all locations",
"properties": {
"1": {
"description": "Total 1-star ratings across all locations",
"type": "integer",
"example": 2
},
"2": {
"description": "Total 2-star ratings across all locations",
"type": "integer",
"example": 3
},
"3": {
"description": "Total 3-star ratings across all locations",
"type": "integer",
"example": 8
},
"4": {
"description": "Total 4-star ratings across all locations",
"type": "integer",
"example": 15
},
"5": {
"description": "Total 5-star ratings across all locations",
"type": "integer",
"example": 17
}
},
"type": "object"
}
},
"type": "object"
},
"by_stations": {
"description": "Aggregated ratings data across all stations",
"properties": {
"average_participants": {
"description": "Average participation percentage across all stations",
"type": "number",
"format": "float",
"example": 78.3
},
"total_reviews": {
"description": "Total reviews across all stations",
"type": "integer",
"example": 32
},
"average": {
"description": "Average rating across all stations",
"type": "number",
"format": "float",
"example": 4.3
},
"distribution": {
"description": "Aggregated rating distribution across all stations",
"properties": {
"1": {
"description": "Total 1-star ratings across all stations",
"type": "integer",
"example": 1
},
"2": {
"description": "Total 2-star ratings across all stations",
"type": "integer",
"example": 2
},
"3": {
"description": "Total 3-star ratings across all stations",
"type": "integer",
"example": 5
},
"4": {
"description": "Total 4-star ratings across all stations",
"type": "integer",
"example": 12
},
"5": {
"description": "Total 5-star ratings across all stations",
"type": "integer",
"example": 12
}
},
"type": "object"
}
},
"type": "object"
},
"by_services": {
"description": "Aggregated ratings data across all services",
"properties": {
"average_participants": {
"description": "Average participation percentage across all services",
"type": "number",
"format": "float",
"example": 92.1
},
"total_reviews": {
"description": "Total reviews across all services",
"type": "integer",
"example": 67
},
"average": {
"description": "Average rating across all services",
"type": "number",
"format": "float",
"example": 4.4
},
"distribution": {
"description": "Aggregated rating distribution across all services",
"properties": {
"1": {
"description": "Total 1-star ratings across all services",
"type": "integer",
"example": 3
},
"2": {
"description": "Total 2-star ratings across all services",
"type": "integer",
"example": 4
},
"3": {
"description": "Total 3-star ratings across all services",
"type": "integer",
"example": 10
},
"4": {
"description": "Total 4-star ratings across all services",
"type": "integer",
"example": 25
},
"5": {
"description": "Total 5-star ratings across all services",
"type": "integer",
"example": 25
}
},
"type": "object"
}
},
"type": "object"
},
"by_categories": {
"description": "Aggregated ratings data across all client categories",
"properties": {
"average_participants": {
"description": "Average participation percentage across all categories",
"type": "number",
"format": "float",
"example": 88.7
},
"total_reviews": {
"description": "Total reviews across all categories",
"type": "integer",
"example": 89
},
"average": {
"description": "Average rating across all categories",
"type": "number",
"format": "float",
"example": 4
},
"distribution": {
"description": "Aggregated rating distribution across all categories",
"properties": {
"1": {
"description": "Total 1-star ratings across all categories",
"type": "integer",
"example": 5
},
"2": {
"description": "Total 2-star ratings across all categories",
"type": "integer",
"example": 7
},
"3": {
"description": "Total 3-star ratings across all categories",
"type": "integer",
"example": 15
},
"4": {
"description": "Total 4-star ratings across all categories",
"type": "integer",
"example": 30
},
"5": {
"description": "Total 5-star ratings across all categories",
"type": "integer",
"example": 32
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience-setting": {
"get": {
"tags": [
"Patient Experience Settings"
],
"summary": "Get patient experience settings",
"description": "Retrieve the patient experience settings for the business",
"operationId": "db40bcc374431458a17c5e2e94ff09fc",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/PeSettingResource"
},
"message": {
"type": "string",
"example": "patient experience setting retrieved successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Patient Experience Settings"
],
"summary": "Update patient experience settings",
"description": "Update the patient experience settings for the business. All fields are optional for partial updates.",
"operationId": "41ab70b14ff627cfca8291d944d6ad8c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PeSettingRequest"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/PeSettingResource"
},
"message": {
"type": "string",
"example": "patient experience setting updated successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/stats": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "Get feedback statistics",
"description": "Retrieve aggregated statistics and metrics for patient Experience",
"operationId": "2cad1e0d5d7448d9e506b921b3896cbe",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"stats": {
"properties": {
"total_submissions": {
"type": "integer",
"example": 100
},
"completed_submissions": {
"type": "integer",
"example": 80
},
"completion_rate": {
"type": "number",
"example": 80
},
"average_rating": {
"type": "number",
"example": 4.5
},
"rating_distribution": {
"properties": {
"1": {
"type": "integer",
"example": 5
},
"2": {
"type": "integer",
"example": 3
},
"3": {
"type": "integer",
"example": 10
},
"4": {
"type": "integer",
"example": 22
},
"5": {
"type": "integer",
"example": 60
}
},
"type": "object"
},
"total_reviews": {
"type": "integer",
"example": 80
}
},
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Feedback stats retrieved successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/feedbacks": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "List patient Experience responses",
"description": "Retrieve a list of patient Experience responses with optional filters, sorting, and pagination. When pagination parameters are provided, returns paginated results with meta information.",
"operationId": "302a346b9972543379398f17e580324a",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationHeader"
},
{
"$ref": "#/components/parameters/LocationIdsFilter"
},
{
"$ref": "#/components/parameters/CategoryIdsFilter"
},
{
"$ref": "#/components/parameters/StationIdsFilter"
},
{
"$ref": "#/components/parameters/ServiceIdsFilter"
},
{
"$ref": "#/components/parameters/ClientIdsFilter"
},
{
"$ref": "#/components/parameters/DateFromFilter"
},
{
"$ref": "#/components/parameters/DateToFilter"
},
{
"name": "min_rating",
"in": "query",
"description": "Minimum rating to filter by (1-5)",
"required": false,
"schema": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"example": 3
}
},
{
"name": "max_rating",
"in": "query",
"description": "Maximum rating to filter by (1-5)",
"required": false,
"schema": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"example": 5
}
},
{
"name": "search",
"in": "query",
"description": "Search term for patient name or feedback content",
"required": false,
"schema": {
"type": "string",
"example": "John"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"required": false,
"schema": {
"type": "string",
"enum": [
"patient_name",
"location",
"service",
"rating",
"submitted_at"
],
"example": "submitted_at"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination (triggers paginated response)",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (triggers paginated response)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Successful operation - Returns either paginated or non-paginated response based on parameters",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Non-paginated response (when page/per_page not provided)",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedbacks retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Feedback"
}
}
},
"type": "object"
},
{
"description": "Paginated response (when page/per_page provided)",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedbacks retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Feedback"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"description": "Total number of items",
"type": "integer",
"example": 150
},
"count": {
"description": "Number of items in current page",
"type": "integer",
"example": 20
},
"per_page": {
"description": "Items per page",
"type": "integer",
"example": 20
},
"current_page": {
"description": "Current page number",
"type": "integer",
"example": 1
},
"total_pages": {
"description": "Total number of pages",
"type": "integer",
"example": 8
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/feedbacks/{responseUUid}": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "Get detailed feedback",
"description": "Retrieve detailed information for a specific feedback response, including general feedback and field responses",
"operationId": "e87f41e1194ee80ffa34a07d5606db21",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "responseUUid",
"in": "path",
"description": "UUID of the feedback response",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/FeedbackDetailResource"
},
"message": {
"type": "string",
"example": "Feedback detail retrieved successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Feedback not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Requested response not found"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/summaries": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "List feedback summaries",
"description": "Retrieve a list of feedback question summaries with response counts, sorting, and optional pagination. The response structure varies based on field type (has_options in config/field_types.php). For option-based fields like satisfaction_scale, responses will be aggregated by option. For text fields, only the response count is shown (detailed responses available in detail endpoint). When pagination parameters are provided, returns paginated results with meta information.",
"operationId": "bbf0184aa817b5796b3e725ad6c09c7b",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationHeader"
},
{
"$ref": "#/components/parameters/LocationIdsFilter"
},
{
"$ref": "#/components/parameters/CategoryIdsFilter"
},
{
"$ref": "#/components/parameters/StationIdsFilter"
},
{
"$ref": "#/components/parameters/ServiceIdsFilter"
},
{
"$ref": "#/components/parameters/ClientIdsFilter"
},
{
"$ref": "#/components/parameters/DateFromFilter"
},
{
"$ref": "#/components/parameters/DateToFilter"
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"required": false,
"schema": {
"type": "string",
"enum": [
"question",
"station",
"location",
"service",
"total_response_count",
"latest_response_date"
],
"example": "latest_response_date"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination (triggers paginated response)",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (triggers paginated response)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Successful operation - Returns either paginated or non-paginated response based on parameters",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Non-paginated response (when page/per_page not provided)",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback summaries retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FeedbackSummary"
}
}
},
"type": "object"
},
{
"description": "Paginated response (when page/per_page provided)",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback summaries retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FeedbackSummary"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"description": "Total number of items",
"type": "integer",
"example": 75
},
"count": {
"description": "Number of items in current page",
"type": "integer",
"example": 15
},
"per_page": {
"description": "Items per page",
"type": "integer",
"example": 15
},
"current_page": {
"description": "Current page number",
"type": "integer",
"example": 1
},
"total_pages": {
"description": "Total number of pages",
"type": "integer",
"example": 5
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/summaries/{responseUUid}": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "Get feedback summary detail",
"description": "Retrieve detailed response data for a specific feedback question. The response format varies based on field type (has_options in config/field_types.php). Option-based fields show counts per option, while text fields show individual responses with client info.",
"operationId": "2fd77e28561b2eb24d4866be5c627b78",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "responseUUid",
"in": "path",
"description": "UUID of the feedback question",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback summary detail retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/FeedbackSummaryDetail"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/feedbacks/details": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "List all patient feedback details",
"description": "Retrieve a complete list of patient feedback responses in detailed format with optional filters and sorting. Returns all feedback details without pagination.",
"operationId": "43ed77522e1cfa5a01078b10cd2a5afd",
"parameters": [
{
"$ref": "#/components/parameters/StationIdsFilter"
},
{
"$ref": "#/components/parameters/LocationIdsFilter"
},
{
"$ref": "#/components/parameters/ServiceIdsFilter"
},
{
"$ref": "#/components/parameters/CategoryIdsFilter"
},
{
"$ref": "#/components/parameters/DateFromFilter"
},
{
"$ref": "#/components/parameters/DateToFilter"
},
{
"name": "min_rating",
"in": "query",
"description": "Minimum rating filter",
"required": false,
"schema": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"example": 3
}
},
{
"name": "max_rating",
"in": "query",
"description": "Maximum rating filter",
"required": false,
"schema": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"example": 5
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"required": false,
"schema": {
"type": "string",
"enum": [
"patient_name",
"location",
"service",
"rating",
"submitted_at"
],
"example": "submitted_at"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback details retrieved successfully"
},
"data": {
"description": "Array of detailed feedback objects with all related data",
"type": "array",
"items": {
"$ref": "#/components/schemas/FeedbackDetailResource"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-experience/summaries/details": {
"get": {
"tags": [
"Patient Experience"
],
"summary": "List all feedback summary details",
"description": "Retrieve a complete list of feedback question summaries in detailed format with response breakdowns, filtering, and sorting. Returns all summary details without pagination.",
"operationId": "f9d11481b82b6e5f6975cd46d1276387",
"parameters": [
{
"$ref": "#/components/parameters/StationIdsFilter"
},
{
"$ref": "#/components/parameters/LocationIdsFilter"
},
{
"$ref": "#/components/parameters/ServiceIdsFilter"
},
{
"$ref": "#/components/parameters/CategoryIdsFilter"
},
{
"$ref": "#/components/parameters/DateFromFilter"
},
{
"$ref": "#/components/parameters/DateToFilter"
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"required": false,
"schema": {
"type": "string",
"enum": [
"question",
"station",
"location",
"service",
"total_response_count",
"latest_response_date"
],
"example": "latest_response_date"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Summary details retrieved successfully"
},
"data": {
"description": "Array of detailed summary objects with response breakdowns and analysis",
"type": "array",
"items": {
"properties": {
"question_id": {
"type": "string",
"example": "field-uuid-123::1::2::null"
},
"question": {
"type": "string",
"example": "How satisfied are you with our service?"
},
"field_type": {
"type": "string",
"example": "satisfaction_scale"
},
"total_response_count": {
"type": "integer",
"example": 45
},
"location_name": {
"type": "string",
"example": "Main Clinic"
},
"station_name": {
"type": "string",
"example": "Reception"
},
"service_name": {
"type": "string",
"example": "Consultation"
},
"responses": {
"description": "Detailed breakdown of responses",
"type": "array",
"items": {
"properties": {
"option_text": {
"type": "string",
"example": "Very Satisfied"
},
"response_count": {
"type": "integer",
"example": 15
},
"percentage": {
"type": "number",
"format": "float",
"example": 33.33
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/settings/pii-redaction/available-fields": {
"get": {
"tags": [
"PII Redaction Settings"
],
"summary": "Get available fields for PII redaction",
"description": "Returns a list of all system fields that can be configured for automatic PII redaction.",
"operationId": "e3416b12d74d8b3e4c586175eb95e86d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Available fields retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Available fields retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "phone_number"
},
"label": {
"type": "string",
"example": "Phone Number"
},
"description": {
"type": "string",
"example": "Patient's phone number"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/settings/pii-redaction": {
"get": {
"tags": [
"PII Redaction Settings"
],
"summary": "Get PII redaction settings",
"description": "Returns the organization's PII redaction configuration.",
"operationId": "a476cac1414012475fb03ab869e295c2",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "PII redaction settings retrieved successfully"
},
"data": {
"properties": {
"enabled": {
"type": "boolean",
"example": true
},
"fields": {
"type": "array",
"items": {
"type": "string",
"example": "phone_number"
}
},
"attributes": {
"type": "array",
"items": {
"type": "string",
"example": "date_of_birth"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"PII Redaction Settings"
],
"summary": "Update PII redaction settings",
"description": "Update the organization's PII redaction configuration. When enabled, new patients will have specified fields automatically redacted.",
"operationId": "e98acdf8b793e7b0616c6f8b0bcac75a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"enabled"
],
"properties": {
"enabled": {
"description": "Whether auto-redaction is enabled",
"type": "boolean",
"example": true
},
"fields": {
"description": "System fields to redact (first_name, last_name, email, phone_number, profile_picture_url, external_id)",
"type": "array",
"items": {
"type": "string",
"example": "phone_number"
}
},
"attributes": {
"description": "Custom attribute keys to redact",
"type": "array",
"items": {
"type": "string",
"example": "date_of_birth"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Settings updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "PII redaction settings updated successfully"
},
"data": {
"properties": {
"enabled": {
"type": "boolean",
"example": true
},
"fields": {
"type": "array",
"items": {
"type": "string"
}
},
"attributes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/settings/pii-redaction/enable": {
"post": {
"tags": [
"PII Redaction Settings"
],
"summary": "Enable PII auto-redaction",
"description": "Quick enable PII auto-redaction with specified fields.",
"operationId": "022dc54fbd20e65c9b0d52cc22876b83",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"fields": {
"description": "System fields to redact",
"type": "array",
"items": {
"type": "string",
"example": "phone_number"
}
},
"attributes": {
"description": "Custom attribute keys to redact",
"type": "array",
"items": {
"type": "string",
"example": "date_of_birth"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Auto-redaction enabled successfully"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/settings/pii-redaction/disable": {
"post": {
"tags": [
"PII Redaction Settings"
],
"summary": "Disable PII auto-redaction",
"description": "Disable PII auto-redaction for the organization.",
"operationId": "d850fe532194fb3720fbb225834bc07d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Auto-redaction disabled successfully"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/user-notifications": {
"get": {
"tags": [
"User Notifications"
],
"summary": "List user notifications",
"description": "Get paginated list of user notifications with filtering options",
"operationId": "a83352c65da02cd1e37cbcc07d5a0ab6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "unread",
"in": "query",
"description": "Filter for unread notifications only",
"required": false,
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"example": "true"
}
},
{
"name": "client_ids",
"in": "query",
"description": "Filter by specific client IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "actions",
"in": "query",
"description": "Filter by specific actions",
"required": false,
"schema": {
"type": "string",
"example": "login,logout,update"
}
},
{
"name": "location_ids",
"in": "query",
"description": "Filter by specific location IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter by specific location station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "user_ids",
"in": "query",
"description": "Filter by specific action user IDs (who performed the action)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "start_date",
"in": "query",
"description": "Filter notifications from this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "Filter notifications until this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search in notification message",
"required": false,
"schema": {
"type": "string",
"example": "login attempt"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by notification type",
"required": false,
"schema": {
"type": "string",
"enum": [
"schedule",
"waitlist",
"system",
"appointment"
],
"example": "schedule"
}
},
{
"name": "limit",
"in": "query",
"description": "Limit the number of notifications to return",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"message": {
"type": "string",
"example": "User logged in successfully"
},
"is_read": {
"type": "boolean",
"example": false
},
"action_user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"profile_picture": {
"type": "string",
"example": "https://example.com/profile.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"type": {
"type": "string",
"example": "login"
},
"type_id": {
"type": "integer",
"example": 101
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 101
},
"name": {
"type": "string",
"example": "Client Name"
},
"email": {
"type": "string",
"example": "client@example.com"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/client-profile.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"meta": {
"type": "object"
},
"unread_count": {
"type": "integer",
"example": 5
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Notifications fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/user-notifications/get-all": {
"get": {
"tags": [
"User Notifications"
],
"summary": "Get all user notifications without pagination",
"description": "Get all user notifications with filtering options but without pagination",
"operationId": "0f125b30cbc9d3fd6b14e7f745740c74",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "unread",
"in": "query",
"description": "Filter for unread notifications only",
"required": false,
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"example": "true"
}
},
{
"name": "client_ids",
"in": "query",
"description": "Filter by specific client IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "actions",
"in": "query",
"description": "Filter by specific actions",
"required": false,
"schema": {
"type": "string",
"example": "login,logout,update"
}
},
{
"name": "location_ids",
"in": "query",
"description": "Filter by specific location IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter by specific location station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "user_ids",
"in": "query",
"description": "Filter by specific action user IDs (who performed the action)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "start_date",
"in": "query",
"description": "Filter notifications from this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "Filter notifications until this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search in notification message",
"required": false,
"schema": {
"type": "string",
"example": "login attempt"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by notification type",
"required": false,
"schema": {
"type": "string",
"enum": [
"schedule",
"waitlist",
"system",
"appointment"
],
"example": "schedule"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"message": {
"type": "string",
"example": "User logged in successfully"
},
"is_read": {
"type": "boolean",
"example": false
},
"action_user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"profile_picture": {
"type": "string",
"example": "https://example.com/profile.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"type": {
"type": "string",
"example": "login"
},
"type_id": {
"type": "integer",
"example": 101
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 101
},
"name": {
"type": "string",
"example": "Client Name"
},
"email": {
"type": "string",
"example": "client@example.com"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/client-profile.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"unread_count": {
"type": "integer",
"example": 5
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "All notifications fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/user-notifications/mark-all-read": {
"post": {
"tags": [
"User Notifications"
],
"summary": "Mark all notifications as read",
"description": "Mark all or specific notifications as read for the authenticated user",
"operationId": "ebe6ee62a11d57eadb2ddb72bf8905c3",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "Array of specific notification IDs to mark as read. If not provided, all unread notifications will be marked as read.",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "null",
"example": null
},
"message": {
"type": "string",
"example": "All notifications marked as read."
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/user-notifications/actions": {
"get": {
"tags": [
"User Notifications"
],
"summary": "List available notification actions",
"description": "Get list of all unique actions available in user notifications",
"operationId": "e60369c9d80e988d4834655b248e23f6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"properties": {
"action": {
"type": "string",
"example": "login"
}
},
"type": "object"
}
},
"message": {
"type": "string",
"example": "Actions fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/access-logs": {
"get": {
"tags": [
"Logs"
],
"summary": "List access logs",
"description": "Get paginated list of access logs with filtering options",
"operationId": "991f2e37eecd9e748f832e27575bc08e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "actions",
"in": "query",
"description": "Filter by specific actions",
"required": false,
"schema": {
"type": "string",
"example": "login,logout,update"
}
},
{
"name": "action",
"in": "query",
"description": "Filter by specific action",
"required": false,
"schema": {
"type": "string",
"example": "login"
}
},
{
"name": "start_date",
"in": "query",
"description": "Filter logs from this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "Filter logs until this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search in log detail, action, or IP",
"required": false,
"schema": {
"type": "string",
"example": "login attempt"
}
},
{
"name": "ip",
"in": "query",
"description": "Filter by IP address",
"required": false,
"schema": {
"type": "string",
"example": "192.168.1.1"
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by location ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "location_station_id",
"in": "query",
"description": "Filter by location station ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "limit",
"in": "query",
"description": "Limit the number of logs to return",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"business_id": {
"type": "integer",
"example": 1
},
"detail": {
"type": "string",
"example": "User logged in successfully"
},
"ip": {
"type": "string",
"example": "192.168.1.1"
},
"action": {
"type": "string",
"example": "login"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Access logs fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/access-logs/get-all": {
"get": {
"tags": [
"Logs"
],
"summary": "Get all access logs without pagination",
"description": "Get all access logs with filtering options but without pagination",
"operationId": "9bd4e065dc0f309c03812083cc0e06b7",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "actions",
"in": "query",
"description": "Filter by specific actions",
"required": false,
"schema": {
"type": "string",
"example": "login,logout,update"
}
},
{
"name": "action",
"in": "query",
"description": "Filter by specific action",
"required": false,
"schema": {
"type": "string",
"example": "login"
}
},
{
"name": "start_date",
"in": "query",
"description": "Filter logs from this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "Filter logs until this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search in log details and user information",
"required": false,
"schema": {
"type": "string",
"example": "user login"
}
},
{
"name": "ip",
"in": "query",
"description": "Filter by IP address",
"required": false,
"schema": {
"type": "string",
"example": "192.168.1.1"
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by specific location IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "location_station_id",
"in": "query",
"description": "Filter by specific location station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by specific station IDs (legacy)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter by specific station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "user_ids",
"in": "query",
"description": "Filter by specific user IDs (who performed the action)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"action": {
"type": "string",
"example": "login"
},
"detail": {
"type": "string",
"example": "User logged in successfully"
},
"ip": {
"type": "string",
"example": "192.168.1.1"
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"profile_picture": {
"type": "string",
"example": "https://example.com/profile.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"message": {
"type": "string",
"example": "All access logs fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/access-logs/actions": {
"get": {
"tags": [
"Logs"
],
"summary": "Get available access log actions",
"description": "Get list of available actions for access logs in the business",
"operationId": "e6fe338aee67284292dfcbd65c437f37",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "string",
"example": "login"
}
},
"message": {
"type": "string",
"example": "Access log actions fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/audit-logs": {
"get": {
"tags": [
"Logs"
],
"summary": "List audit logs",
"description": "Get paginated list of audit logs with filtering options",
"operationId": "8acc9b3e1ab26c59542d5c8144e60649",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "actions",
"in": "query",
"description": "Filter by specific actions",
"required": false,
"schema": {
"type": "string",
"example": "create,update,delete"
}
},
{
"name": "action",
"in": "query",
"description": "Filter by specific action",
"required": false,
"schema": {
"type": "string",
"example": "update"
}
},
{
"name": "start_date",
"in": "query",
"description": "Filter logs from this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "Filter logs until this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search in log detail, action, or IP",
"required": false,
"schema": {
"type": "string",
"example": "profile update"
}
},
{
"name": "ip",
"in": "query",
"description": "Filter by IP address",
"required": false,
"schema": {
"type": "string",
"example": "192.168.1.1"
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by location ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "location_station_id",
"in": "query",
"description": "Filter by location station ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID(s)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "limit",
"in": "query",
"description": "Limit the number of logs to return",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"business_id": {
"type": "integer",
"example": 1
},
"detail": {
"type": "string",
"example": "User updated profile"
},
"ip": {
"type": "string",
"example": "192.168.1.1"
},
"action": {
"type": "string",
"example": "update"
},
"old_data": {
"type": "object",
"example": {
"name": "Old Name"
}
},
"new_data": {
"type": "object",
"example": {
"name": "New Name"
}
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Audit logs fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/audit-logs/get-all": {
"get": {
"tags": [
"Logs"
],
"summary": "Get all audit logs without pagination",
"description": "Get all audit logs with filtering options but without pagination",
"operationId": "041d955c60dee64bc83b2e37b66984c9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "actions",
"in": "query",
"description": "Filter by specific actions",
"required": false,
"schema": {
"type": "string",
"example": "create,update,delete"
}
},
{
"name": "action",
"in": "query",
"description": "Filter by specific action",
"required": false,
"schema": {
"type": "string",
"example": "update"
}
},
{
"name": "start_date",
"in": "query",
"description": "Filter logs from this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "Filter logs until this date (inclusive)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search in log details and user information",
"required": false,
"schema": {
"type": "string",
"example": "user update"
}
},
{
"name": "ip",
"in": "query",
"description": "Filter by IP address",
"required": false,
"schema": {
"type": "string",
"example": "192.168.1.1"
}
},
{
"name": "schedule_type",
"in": "query",
"description": "Filter by schedule type",
"required": false,
"schema": {
"type": "string",
"example": "appointment"
}
},
{
"name": "client_id",
"in": "query",
"description": "Filter by client ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by specific location IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "location_station_id",
"in": "query",
"description": "Filter by specific location station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by specific station IDs (legacy)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter by specific station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "user_ids",
"in": "query",
"description": "Filter by specific user IDs (who performed the action)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"action": {
"type": "string",
"example": "update"
},
"detail": {
"type": "string",
"example": "User updated profile"
},
"ip": {
"type": "string",
"example": "192.168.1.1"
},
"schedule_type": {
"type": "string",
"example": "appointment",
"nullable": true
},
"client_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"profile_picture": {
"type": "string",
"example": "https://example.com/profile.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"message": {
"type": "string",
"example": "All audit logs fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/audit-logs/actions": {
"get": {
"tags": [
"Logs"
],
"summary": "Get available audit log actions",
"description": "Get list of available actions for audit logs in the business",
"operationId": "4041ac803a85eadafcbe698da6d33d14",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "string",
"example": "update"
}
},
"message": {
"type": "string",
"example": "Audit log actions fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/validation-settings": {
"get": {
"tags": [
"Validation Settings"
],
"summary": "Get validation settings for the business",
"operationId": "d4816e2fdd2288f09e695a146dc975df",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"is_validation_enabled": {
"type": "boolean",
"example": true
},
"is_verification_enabled": {
"type": "boolean",
"example": false
},
"is_client_allowed_to_update_profile": {
"type": "boolean",
"example": true
},
"is_client_allowed_to_update_email": {
"type": "boolean",
"example": false
},
"verification_question": {
"type": "string",
"example": "What is your favorite color?"
},
"verification_redirect_url": {
"type": "string",
"example": "https://example.com/redirect"
},
"verification_redirect_answer_value": {
"type": "string",
"example": "blue"
},
"fields": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Email"
}
},
"type": "object"
}
},
"selected_validation_fields": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Organization validation setting fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Validation Settings"
],
"summary": "Update validation settings for the business",
"operationId": "c7a97c50bca74e481984c806307edec4",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"is_validation_enabled"
],
"properties": {
"is_validation_enabled": {
"description": "Whether client validation is enabled",
"type": "boolean",
"example": true
},
"is_verification_enabled": {
"description": "Whether verification is enabled",
"type": "boolean",
"example": false
},
"is_client_allowed_to_update_profile": {
"description": "Whether client client can update their profile",
"type": "boolean",
"example": true
},
"is_client_allowed_to_update_email": {
"description": "Whether Clients are allowed to change their email",
"type": "boolean",
"example": false
},
"verification_question": {
"description": "Question for verification",
"type": "string",
"example": "What is your favorite color?",
"nullable": true
},
"verification_redirect_url": {
"description": "URL to redirect after verification",
"type": "string",
"example": "https://example.com/redirect",
"nullable": true
},
"verification_redirect_answer_value": {
"description": "Answer value that triggers redirect (yes/no)",
"type": "string",
"example": "yes",
"nullable": true
},
"selected_validation_fields": {
"description": "Array of attribute IDs to use as validators (must be at least 2 if validation is enabled)",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"is_validation_enabled": {
"type": "boolean",
"example": true
},
"is_verification_enabled": {
"type": "boolean",
"example": false
},
"verification_question": {
"type": "string",
"example": "What is your favorite color?"
},
"verification_redirect_url": {
"type": "string",
"example": "https://example.com/redirect"
},
"verification_redirect_answer_value": {
"type": "string",
"example": "yes"
},
"fields": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Email"
}
},
"type": "object"
}
},
"selected_validation_fields": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Validation settings updated successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/walk-in-settings": {
"get": {
"tags": [
"Walk-in Settings"
],
"summary": "Get or create walk-in settings",
"description": "Retrieve the walk-in settings for the current business, location, or station scope. Automatically creates defaults if not existing.",
"operationId": "getWalkInSetting",
"parameters": [
{
"name": "location_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "location_station_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Walk-in setting retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInSettingResource"
}
}
}
},
"404": {
"description": "Scope not found"
},
"401": {
"description": "Unauthenticated"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Walk-in Settings"
],
"summary": "Update walk-in settings",
"description": "Update walk-in settings for a specific business, location, or station. Automatically creates defaults if not existing.",
"operationId": "updateWalkInSetting",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInSettingResource"
}
}
}
},
"responses": {
"200": {
"description": "Walk-in settings updated successfully"
},
"400": {
"description": "Validation failed"
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/walk-in-settings/general": {
"get": {
"tags": [
"Walk-in Settings"
],
"summary": "Get general walk-in settings",
"description": "Get only general walk-in settings",
"operationId": "getGeneralWalkInSetting",
"responses": {
"200": {
"description": "General walk-in settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInGeneralSettingResource"
}
}
}
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Walk-in Settings"
],
"summary": "Update general walk-in settings",
"description": "Update only general walk-in settings. Use flat structure without 'general' key.",
"operationId": "updateGeneralWalkInSetting",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [],
"properties": {
"wait_time_calculation": {
"properties": {
"method": {
"type": "string",
"enum": [
"historical_average",
"custom"
],
"example": "custom"
},
"custom_wait_time": {
"type": "integer",
"example": 15,
"nullable": true
}
},
"type": "object"
},
"queue_length_cap": {
"properties": {
"enabled": {
"type": "boolean",
"example": true
},
"maximum_number": {
"type": "integer",
"example": 15,
"nullable": true
}
},
"type": "object"
},
"allow_walk_ins": {
"type": "boolean",
"example": true
},
"carry_over_walk_ins": {
"type": "boolean",
"example": true
},
"maximum_allowed_late_time": {
"type": "integer",
"example": 10
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "General walk-in settings updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInGeneralSettingResource"
}
}
}
},
"400": {
"description": "Validation failed"
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/walk-in-settings/patient-experience": {
"get": {
"tags": [
"Walk-in Settings"
],
"summary": "Get patient experiences of walk-in settings",
"description": "Get only patient experiences of walk-in settings",
"operationId": "getWalkInPatientExperienceSetting",
"responses": {
"200": {
"description": "Walk-in patient experience settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInPatientExperienceSettingResource"
}
}
}
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Walk-in Settings"
],
"summary": "Update patient experience walk-in settings",
"description": "Update only patient experience walk-in settings. Use flat structure without 'patient_experience' key.",
"operationId": "updatePatientExperienceWalkInSetting",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [],
"properties": {
"show_queue_position": {
"type": "boolean",
"example": true
},
"show_estimated_wait_time": {
"type": "boolean",
"example": true
},
"show_real_time_updates": {
"type": "boolean",
"example": false
},
"update_frequency": {
"type": "integer",
"example": 5,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient experience walk-in settings updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInPatientExperienceSettingResource"
}
}
}
},
"400": {
"description": "Validation failed"
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/walk-in-settings/cancellation-rules": {
"get": {
"tags": [
"Walk-in Settings"
],
"summary": "Get cancellation rules walk-in settings",
"description": "Get only cancellation rules walk-in settings",
"operationId": "getWalkInCancellationRules",
"responses": {
"200": {
"description": "Cancellation rules walk-in settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInCancellationSettingResource"
}
}
}
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Walk-in Settings"
],
"summary": "Update cancellation rules walk-in settings",
"description": "Update only cancellation rules walk-in settings. Use flat structure without 'cancellation_rules' key.",
"operationId": "updateCancellationRules",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [],
"properties": {
"allow_cancellation_with_alert": {
"type": "boolean",
"example": true
},
"cancellation_alert": {
"properties": {
"time_threshold": {
"type": "integer",
"example": 30
},
"time_unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days"
],
"example": "minutes"
},
"relation": {
"type": "string",
"enum": [
"before",
"after"
],
"example": "before"
}
},
"type": "object",
"nullable": true
},
"custom_messages": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "reminder-1"
},
"content": {
"type": "string",
"example": "Your walk-in booking will start soon."
},
"max_characters": {
"type": "integer",
"example": 160
},
"delivery_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"in_app",
"sms",
"email"
]
}
},
"conditions": {
"type": "array",
"items": {
"type": "string",
"example": "before_start"
},
"nullable": true
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Cancellation rules walk-in settings updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInCancellationSettingResource"
}
}
}
},
"400": {
"description": "Validation failed"
},
"401": {
"description": "Unauthenticated"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/onboarding": {
"post": {
"tags": [
"Onboarding"
],
"summary": "Create business profile",
"description": "Complete business onboarding by creating a business profile with details, working hours, and queue settings. User becomes business owner. If email is not provided in business_details, it will automatically use the logged-in user's email.",
"operationId": "createBusiness",
"requestBody": {
"description": "Complete business onboarding data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"business_details",
"working_hours"
],
"properties": {
"business_details": {
"$ref": "#/components/schemas/BusinessDetails"
},
"working_hours": {
"description": "Business operating hours for each day",
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkingHours"
},
"example": [
{
"day": "monday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "tuesday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "wednesday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "thursday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "friday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "saturday",
"start_time": "10:00",
"end_time": "14:00",
"is_open": true
},
{
"day": "sunday",
"start_time": "00:00",
"end_time": "00:00",
"is_open": false
}
]
},
"queue_settings": {
"$ref": "#/components/schemas/QueueSettings"
}
},
"type": "object"
},
"example": {
"business_details": {
"name": "Acme Medical Clinic",
"address": "123 Main Street",
"country": "United States",
"state": "California",
"city": "San Francisco",
"zip_code": "94102",
"phone_number": "+1-555-123-4567",
"email": "contact@acmemedical.com",
"business_category_id": 1
},
"working_hours": [
{
"day": "monday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "tuesday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "wednesday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "thursday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "friday",
"start_time": "09:00",
"end_time": "17:00",
"is_open": true
},
{
"day": "saturday",
"start_time": "10:00",
"end_time": "14:00",
"is_open": true
},
{
"day": "sunday",
"start_time": "00:00",
"end_time": "00:00",
"is_open": false
}
],
"queue_settings": {
"time_zone": "America/Los_Angeles",
"schedule_block_in_minute": 30,
"manual_wait_time": 15
}
}
}
}
},
"responses": {
"201": {
"description": "Business created successfully - User is now business owner",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Business created successfully"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized - Authentication required",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed - Invalid business data",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ValidationErrorResponse"
},
{
"properties": {
"errors": {
"properties": {
"business_details.name": {
"type": "array",
"items": {
"type": "string",
"example": "The business details.name field is required."
}
},
"business_details.business_category_id": {
"type": "array",
"items": {
"type": "string",
"example": "The selected business details.business category id is invalid."
}
},
"working_hours": {
"type": "array",
"items": {
"type": "string",
"example": "The working hours field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "An unexpected error occurred"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/organization": {
"get": {
"tags": [
"Organization"
],
"summary": "Get current organization details",
"operationId": "54dfa3c572498f028c00de2aba3cfbda",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of additional fields to include (e.g., location_count,station_count,custom_links)",
"required": false,
"schema": {
"type": "string",
"example": "location_count,station_count,custom_links"
}
}
],
"responses": {
"200": {
"description": "Organization details",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/BusinessDetails"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Organization"
],
"summary": "Update organization profile",
"description": "Update an existing organization profile with new details. Only organization owners can update their organization information.",
"operationId": "updateOrganization",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to update",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Updated organization data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"business_category_id"
],
"properties": {
"name": {
"description": "Organization name",
"type": "string",
"example": "Updated Medical Clinic"
},
"address": {
"description": "Street address",
"type": "string",
"example": "456 Oak Street",
"nullable": true
},
"country": {
"description": "Country name",
"type": "string",
"example": "United States",
"nullable": true
},
"state": {
"description": "State or province",
"type": "string",
"example": "California",
"nullable": true
},
"city": {
"description": "City name",
"type": "string",
"example": "Los Angeles",
"nullable": true
},
"zip_code": {
"description": "Postal/ZIP code",
"type": "string",
"example": "90210",
"nullable": true
},
"phone_number": {
"description": "Organization phone number",
"type": "string",
"example": "+1-555-987-6543"
},
"email": {
"description": "Organization email address",
"type": "string",
"format": "email",
"example": "contact@medicalclinic.com"
},
"business_category_id": {
"description": "ID from business_categories table",
"type": "integer",
"example": 1
},
"logo": {
"description": "Logo URL or base64 string",
"type": "string",
"example": "https://example.com/new-logo.png"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Organization updated successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Organization updated successfully"
},
"data": {
"$ref": "#/components/schemas/BusinessDetails"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized - Authentication required",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - User not authorized to update this organization",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to update this organization"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Organization not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed - Invalid organization data",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ValidationErrorResponse"
},
{
"properties": {
"errors": {
"properties": {
"name": {
"type": "array",
"items": {
"type": "string",
"example": "The name field is required."
}
},
"business_category_id": {
"type": "array",
"items": {
"type": "string",
"example": "The selected business category id is invalid."
}
},
"address": {
"type": "array",
"items": {
"type": "string",
"example": "The address field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "An unexpected error occurred"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Organization"
],
"summary": "Delete organization and all associated data",
"description": "Permanently delete an organization and all its associated data including clients, locations, stations, services, forms, automations, and team members. This action cannot be undone. Only organization owners can delete their organization.",
"operationId": "deleteOrganization",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to delete",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Confirmation data for organization deletion",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"confirm_name"
],
"properties": {
"confirm_name": {
"description": "Organization name to confirm deletion (must match exactly)",
"type": "string",
"example": "Acme Medical Clinic"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Organization deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization 'Acme Medical Clinic' and all associated data deleted successfully"
},
"data": {
"properties": {
"business_id": {
"type": "integer",
"example": 1
},
"business_name": {
"type": "string",
"example": "Acme Medical Clinic"
},
"total_records_deleted": {
"type": "integer",
"example": 542
},
"deleted_counts": {
"properties": {
"clients": {
"type": "integer",
"example": 150
},
"locations": {
"type": "integer",
"example": 3
},
"stations": {
"type": "integer",
"example": 12
},
"services": {
"type": "integer",
"example": 25
},
"business": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Organization name confirmation mismatch",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization name confirmation does not match"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - Authentication required"
},
"403": {
"description": "Forbidden - User not authorized to delete this organization",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to delete this organization. Only organization owners can perform this action."
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Organization not found"
},
"422": {
"description": "Validation failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"confirm_name": {
"type": "array",
"items": {
"type": "string",
"example": "The confirm name field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/theme": {
"post": {
"tags": [
"Organization"
],
"summary": "Change the theme of the organization",
"description": "Allows an authenticated user to change the theme of their organization.",
"operationId": "158cdea63b16403532b47e4a13e95429",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"theme"
],
"properties": {
"theme": {
"description": "The theme to set for the organization",
"type": "string",
"example": "dark"
},
"theme_text_color": {
"description": "Hex color code for theme text (optional)",
"type": "string",
"example": "#FFFFFF"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Theme updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Acme Inc."
},
"theme": {
"type": "string",
"example": "dark"
},
"theme_text_color": {
"type": "string",
"example": "#FFFFFF"
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Theme updated successfully. Your organization's display settings have been changed."
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"errors": {
"properties": {
"theme": {
"type": "array",
"items": {
"type": "string",
"example": "Please select a theme for your organization."
}
}
},
"type": "object"
},
"message": {
"type": "string",
"example": "Validation failed"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "An unexpected error occurred"
}
},
"message": {
"type": "string",
"example": "Server error"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/organization/display-settings": {
"get": {
"tags": [
"Organization Display"
],
"summary": "Get organization display settings",
"description": "Retrieve the current display settings for the organization including logos, banners, colors, and call-to-action settings.",
"operationId": "getOrganizationDisplaySettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Display settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Display settings retrieved successfully"
},
"data": {
"properties": {
"name": {
"description": "Organization name",
"type": "string",
"example": "Acme Medical Clinic"
},
"display_title": {
"description": "Display title shown on landing page",
"type": "string",
"example": "Welcome to Acme Medical"
},
"description": {
"description": "Organization description",
"type": "string",
"example": "Professional healthcare services"
},
"logo": {
"description": "Logo URL",
"type": "string",
"example": "https://example.com/logo.png"
},
"banner": {
"description": "Banner image URL",
"type": "string",
"example": "https://example.com/banner.jpg"
},
"background_image": {
"description": "Background image URL",
"type": "string",
"example": "https://example.com/bg.jpg"
},
"secondary_cta_title": {
"description": "Secondary call-to-action title",
"type": "string",
"example": "Learn More"
},
"secondary_cta_url": {
"description": "Secondary call-to-action URL",
"type": "string",
"example": "https://example.com/learn-more"
},
"background_color": {
"description": "Background color hex code",
"type": "string",
"example": "#ffffff"
},
"theme_text_color": {
"description": "Theme text color hex code",
"type": "string",
"example": "#000000"
},
"theme": {
"description": "Current theme",
"type": "string",
"example": "default"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Organization Display"
],
"summary": "Update organization display settings",
"description": "Update the display settings for the organization including logos, banners, colors, and call-to-action settings.",
"operationId": "updateOrganizationDisplaySettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Display settings data to update",
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"display_title": {
"description": "Display title shown on landing page",
"type": "string",
"example": "Welcome to Our Clinic"
},
"description": {
"description": "Organization description",
"type": "string",
"example": "Professional healthcare services with personalized care"
},
"banner_url": {
"description": "Banner image URL",
"type": "string",
"example": "https://example.com/banner.jpg"
},
"background_image_url": {
"description": "Background image URL",
"type": "string",
"example": "https://example.com/background.jpg"
},
"secondary_cta_title": {
"description": "Secondary call-to-action title",
"type": "string",
"example": "Learn More"
},
"secondary_cta_url": {
"description": "Secondary call-to-action URL",
"type": "string",
"example": "https://example.com/learn-more"
},
"background_color": {
"description": "Background color hex code (e.g., #ffffff)",
"type": "string",
"example": "#ffffff"
},
"theme_text_color": {
"description": "Theme text color hex code (e.g., #000000)",
"type": "string",
"example": "#000000"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Display settings updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Display settings updated successfully"
},
"data": {
"$ref": "#/components/schemas/BusinessDetails"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"background_color": {
"type": "array",
"items": {
"type": "string",
"example": "The background color must be a valid hex color code."
}
},
"theme_text_color": {
"type": "array",
"items": {
"type": "string",
"example": "The theme text color must be a valid hex color code."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso/enable": {
"post": {
"tags": [
"SSO"
],
"summary": "Enable SSO for a business",
"operationId": "39cd06b765b8f20e5f3d346a9cdea6b5",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"entityid",
"loginurl",
"logouturl",
"x509cert",
"email_identification_field"
],
"properties": {
"entityid": {
"type": "string",
"example": "https://idp.example.com/entityid"
},
"loginurl": {
"type": "string",
"example": "https://idp.example.com/login"
},
"logouturl": {
"type": "string",
"example": "https://idp.example.com/logout"
},
"x509cert": {
"type": "string",
"example": "MIIC..."
},
"email_identification_field": {
"type": "string",
"example": "email"
},
"admin_sso": {
"description": "Enable SSO for admin users",
"type": "boolean",
"example": true
},
"admin_force_sso": {
"description": "Force SSO for admin users",
"type": "boolean",
"example": true
},
"patient_sso": {
"description": "Enable SSO for patients/clients",
"type": "boolean",
"example": true
},
"patient_force_sso": {
"description": "Force SSO for patients/clients",
"type": "boolean",
"example": true
},
"status": {
"description": "SSO status - whether SSO is active",
"type": "boolean",
"example": true
},
"message_unregister": {
"type": "string",
"example": "Your account is not registered."
},
"button_unregister": {
"type": "string",
"example": "Register Now"
},
"link_unrregister": {
"type": "string",
"example": "https://example.com/register"
},
"message_restricted": {
"type": "string",
"example": "Access is restricted."
},
"button_restricted": {
"type": "string",
"example": "Contact Support"
},
"link_restricted": {
"type": "string",
"example": "https://example.com/support"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "SSO enabled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO enabled"
},
"data": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"value": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso/update": {
"put": {
"tags": [
"SSO"
],
"summary": "Partially update SSO configuration for a business",
"description": "Only provided fields will be updated; unspecified fields remain unchanged.",
"operationId": "69568a9e7dae9cc44acc9f08aa14a6cf",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"entityid": {
"type": "string",
"example": "https://idp.example.com/entityid"
},
"loginurl": {
"type": "string",
"example": "https://idp.example.com/login"
},
"logouturl": {
"type": "string",
"example": "https://idp.example.com/logout"
},
"x509cert": {
"type": "string",
"example": "MIIC..."
},
"email_identification_field": {
"type": "string",
"example": "email"
},
"admin_sso": {
"type": "boolean",
"example": true
},
"admin_force_sso": {
"type": "boolean",
"example": true
},
"patient_sso": {
"type": "boolean",
"example": true
},
"patient_force_sso": {
"type": "boolean",
"example": true
},
"status": {
"type": "boolean",
"example": true
},
"message_unregister": {
"type": "string",
"example": "Your account is not registered."
},
"button_unregister": {
"type": "string",
"example": "Register Now"
},
"link_unrregister": {
"type": "string",
"example": "https://example.com/register"
},
"message_restricted": {
"type": "string",
"example": "Access is restricted."
},
"button_restricted": {
"type": "string",
"example": "Contact Support"
},
"link_restricted": {
"type": "string",
"example": "https://example.com/support"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "SSO updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO updated"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso": {
"get": {
"tags": [
"SSO"
],
"summary": "Get SSO configuration for a business",
"operationId": "fecd666fe4093c8c170169ba81ffa0bb",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "SSO configuration retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO enabled"
},
"data": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "admin_force_sso"
},
"label": {
"type": "string",
"example": "Admin Force SSO"
},
"value": {
"type": "string",
"example": "true"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"SSO"
],
"summary": "Delete SSO configuration for a business",
"operationId": "9f1fa159e7cd684b35b72d0246578a0a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "SSO disabled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO disabled"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso/config": {
"get": {
"tags": [
"SSO"
],
"summary": "Get raw SSO configuration inputs for a business",
"operationId": "42187a277e45076a0e5c410efaaee0f4",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "SSO configuration inputs retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO configuration retrieved"
},
"data": {
"properties": {
"entityid": {
"type": "string",
"example": "https://idp.example.com/entityid"
},
"loginurl": {
"type": "string",
"example": "https://idp.example.com/login"
},
"logouturl": {
"type": "string",
"example": "https://idp.example.com/logout"
},
"x509cert": {
"type": "string",
"example": "MIIC..."
},
"email_identification_field": {
"type": "string",
"example": "email"
},
"admin_sso": {
"type": "boolean",
"example": true
},
"admin_force_sso": {
"type": "boolean",
"example": true
},
"patient_sso": {
"type": "boolean",
"example": true
},
"patient_force_sso": {
"type": "boolean",
"example": true
},
"status": {
"type": "boolean",
"example": true
},
"message_unregister": {
"type": "string",
"example": "Your account is not registered."
},
"button_unregister": {
"type": "string",
"example": "Register Now"
},
"link_unrregister": {
"type": "string",
"example": "https://example.com/register"
},
"message_restricted": {
"type": "string",
"example": "Access is restricted."
},
"button_restricted": {
"type": "string",
"example": "Contact Support"
},
"link_restricted": {
"type": "string",
"example": "https://example.com/support"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso/claims": {
"get": {
"tags": [
"SSO"
],
"summary": "Get available SSO claims for a business",
"description": "Returns the list of SAML claims/attributes received from the IdP during the last SSO authentication. This helps organizations understand what user attributes are available from their SSO provider.",
"operationId": "647b3fe254124b937333ae1f4984c0c1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "SSO claims retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO claims retrieved"
},
"data": {
"properties": {
"sso_enabled": {
"type": "boolean",
"example": true
},
"claims_available": {
"type": "boolean",
"example": true
},
"claims_updated_at": {
"type": "string",
"format": "date-time",
"example": "2025-11-26T14:30:00Z"
},
"claims": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "emailaddress"
},
"type": {
"type": "string",
"example": "array"
},
"sample_value": {
"type": "string",
"example": "jo***@example.com"
},
"is_multi_valued": {
"type": "boolean",
"example": false
},
"value_count": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"current_email_field": {
"description": "The claim currently configured for email identification",
"type": "string",
"example": "emailaddress"
},
"hint": {
"type": "string",
"example": "Claims are captured during SSO authentication. If no claims are shown, perform an SSO login first."
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "SSO not enabled for this organization"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso/validation-config": {
"get": {
"tags": [
"SSO"
],
"summary": "Get SSO validation configuration for a business",
"description": "Returns the SSO validation settings including which claim to use as external_id for patient verification",
"operationId": "4098b81b8287b35b886a86d9f4bd9ac7",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "SSO validation config retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO validation config retrieved"
},
"data": {
"properties": {
"sso_validation_enabled": {
"type": "boolean",
"example": true
},
"sso_validation_claim": {
"type": "string",
"example": "Studentid"
},
"available_claims": {
"type": "array",
"items": {
"type": "string",
"example": "emailaddress"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "SSO not enabled for this organization"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"SSO"
],
"summary": "Update SSO validation configuration for a business",
"description": "Updates the SSO validation settings. Set sso_validation_claim to the claim key that contains the patient's external ID (e.g., 'Studentid')",
"operationId": "c9207e4564af170f61685f6423825432",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"sso_validation_enabled": {
"description": "Enable/disable automatic patient validation via SSO claims",
"type": "boolean",
"example": true
},
"sso_validation_claim": {
"description": "The SSO claim key to use as external_id for patient validation",
"type": "string",
"example": "Studentid"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "SSO validation config updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "SSO validation config updated"
},
"data": {
"properties": {
"sso_validation_enabled": {
"type": "boolean",
"example": true
},
"sso_validation_claim": {
"type": "string",
"example": "Studentid"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "SSO not enabled for this organization"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/sso/verify": {
"post": {
"tags": [
"SSO"
],
"summary": "Verify SSO login for a business",
"operationId": "0e81459b925a43e2377eed00abe16741",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"type": "string",
"example": "sso_token"
},
"domain": {
"type": "string",
"example": "clinic.example.com",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "SSO verified and user logged in",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Welcome back! You've successfully signed in to your account"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated"
}
}
}
},
"/api/v1/domain/verify": {
"post": {
"tags": [
"Domain"
],
"summary": "Verify domain and retrieve business information",
"description": "Verify a domain and retrieve the associated business information. The domain can be provided in the request body or extracted from the referer header.",
"operationId": "311e821fab2704c99c01b208ed847c1e",
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"domain": {
"description": "Domain to verify. If not provided, will use referer header",
"type": "string",
"example": "https://clinic.example.com"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Business information retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization retrieved"
},
"data": {
"$ref": "#/components/schemas/BusinessDetails"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Organization not found or domain not verified",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/domain/search": {
"post": {
"tags": [
"Domain"
],
"summary": "Search for a business by user email",
"operationId": "4a4417d223b2e9ccaa5891e91b13fe7a",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"example": "user@example.com"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Organization retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization retrieved"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "User or organization not found"
}
}
}
},
"/api/v1/organizations": {
"get": {
"tags": [
"Organization"
],
"summary": "List organizations the current user belongs to",
"operationId": "ae2d743550d527509f094f46bd6fa037",
"parameters": [
{
"name": "include",
"in": "query",
"description": "Comma-separated list of additional fields to include (e.g., location_count,station_count,custom_links)",
"required": false,
"schema": {
"type": "string",
"example": "location_count,station_count,custom_links"
}
}
],
"responses": {
"200": {
"description": "List of organizations the user belongs to",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organizations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BusinessDetails"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/check-unique-name": {
"post": {
"tags": [
"Validation"
],
"summary": "Check if a name is unique for a specific entity type",
"description": "Check if a name is unique for locations, stations, or services within a business",
"operationId": "285aa7e17732ffcd8a0eca1b6565a45c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"entity_type"
],
"properties": {
"name": {
"description": "The name to check for uniqueness",
"type": "string",
"example": "Main Location"
},
"entity_type": {
"description": "The type of entity to check",
"type": "string",
"enum": [
"location",
"station",
"service"
],
"example": "location"
},
"exclude_id": {
"description": "ID to exclude from uniqueness check (for update operations)",
"type": "integer",
"example": 5
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Unique name check result",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Name is available"
},
"data": {
"properties": {
"is_unique": {
"type": "boolean",
"example": true
},
"name": {
"type": "string",
"example": "Main Location"
},
"entity_type": {
"type": "string",
"example": "location"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/organization/domain": {
"get": {
"tags": [
"Organization"
],
"summary": "Get organization domain",
"description": "Retrieve the domain information for the current organization",
"operationId": "81abab60524337272f2899711ba8f723",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Domain information retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Domain retrieved successfully"
},
"data": {
"properties": {
"domain": {
"description": "Organization domain",
"type": "string",
"example": "clinic"
},
"domain_updated": {
"description": "Whether domain needs to be updated (reverse of database value)",
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Organization not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "SSO not enabled",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Enable SSO first"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Enable SSO first"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Organization"
],
"summary": "Update organization domain",
"description": "Update the domain for the current organization. Domain must be unique and follow naming conventions.",
"operationId": "a0cf0abb73fecfdf63f6b784e7303b05",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Domain update data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"domain"
],
"properties": {
"domain": {
"description": "New domain name (alphanumeric, lowercase, no spaces)",
"type": "string",
"example": "newclinic"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Domain updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Domain updated successfully"
},
"data": {
"properties": {
"domain": {
"type": "string",
"example": "newclinic"
},
"domain_updated": {
"description": "Whether domain needs to be updated (reverse of database value)",
"type": "boolean",
"example": false
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation failed or SSO not enabled",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"domain": {
"type": "array",
"items": {
"type": "string",
"example": "The domain field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "Domain already exists",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Domain already exists"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/organization/deletion-preview": {
"get": {
"tags": [
"Organization"
],
"summary": "Get organization deletion preview",
"description": "Get a preview of what data will be deleted when the organization is deleted. This endpoint shows counts of all related records that will be permanently removed.",
"operationId": "getOrganizationDeletionPreview",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Deletion preview retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Deletion preview generated successfully"
},
"data": {
"properties": {
"business_id": {
"type": "integer",
"example": 1
},
"business_name": {
"type": "string",
"example": "Acme Medical Clinic"
},
"estimated_records_to_delete": {
"type": "integer",
"example": 542
},
"breakdown": {
"properties": {
"clients": {
"type": "integer",
"example": 150
},
"locations": {
"type": "integer",
"example": 3
},
"stations": {
"type": "integer",
"example": 12
},
"services": {
"type": "integer",
"example": 25
},
"client_categories": {
"type": "integer",
"example": 8
},
"forms": {
"type": "integer",
"example": 15
},
"automations": {
"type": "integer",
"example": 5
},
"team_members": {
"type": "integer",
"example": 8
}
},
"type": "object"
},
"warning": {
"type": "string",
"example": "This action cannot be undone. All data associated with this organization will be permanently deleted."
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - Authentication required"
},
"404": {
"description": "Organization not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat/messages": {
"post": {
"tags": [
"Chat"
],
"summary": "Send message as user (station provider)",
"description": "Send a message as a station provider to a client. Requires authentication. Real-time notifications are sent to channel: chat.conversation.{stationId}.{clientId}",
"operationId": "sendMessageAsUser",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Message data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_id",
"client_id",
"message"
],
"properties": {
"station_id": {
"description": "ID of the station",
"type": "integer",
"example": 123
},
"client_id": {
"description": "ID of the client",
"type": "integer",
"example": 456
},
"message": {
"description": "Message content",
"type": "string",
"maxLength": 1000,
"example": "Hello! How can I help you today?"
},
"message_type": {
"description": "Type of message",
"type": "string",
"enum": [
"text",
"file",
"image",
"audio",
"video"
],
"example": "text"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Message sent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/patient/chat/messages": {
"post": {
"tags": [
"Patient Chat"
],
"summary": "Send message as patient",
"description": "Send a message as a client to a station provider. No authentication required. Real-time notifications are sent to channel: chat.conversation.{stationId}.{clientId}",
"operationId": "sendMessageAsClient",
"requestBody": {
"description": "Message data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_id",
"client_id",
"message"
],
"properties": {
"station_id": {
"description": "ID of the station",
"type": "integer",
"example": 123
},
"client_id": {
"description": "ID of the client",
"type": "integer",
"example": 456
},
"message": {
"description": "Message content",
"type": "string",
"maxLength": 1000,
"example": "Hello! I have a question."
},
"message_type": {
"description": "Type of message",
"type": "string",
"enum": [
"text",
"file",
"image",
"audio",
"video"
],
"example": "text"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Message sent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/v1/chat/conversations/{stationId}/{clientId}/messages": {
"get": {
"tags": [
"Chat"
],
"summary": "Get conversation history as user (station provider)",
"description": "Retrieve conversation history between a station provider and client. All station users can see all station messages. Unread count shows only client messages (station-level logic). Requires authentication. Listen to channel: chat.conversation.{stationId}.{clientId} for real-time updates.",
"operationId": "getConversationHistoryAsUser",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "stationId",
"in": "path",
"description": "ID of the station",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "clientId",
"in": "path",
"description": "ID of the client",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "limit",
"in": "query",
"description": "Number of messages to retrieve",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1,
"example": 50
}
}
],
"responses": {
"200": {
"description": "Conversation history retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"total": {
"type": "integer",
"example": 1
},
"unread_count": {
"description": "Number of unread client messages",
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/patient/chat/conversations/{stationId}/{clientId}/messages": {
"get": {
"tags": [
"Patient Chat"
],
"summary": "Get conversation history as patient",
"description": "Retrieve conversation history between a station provider and client. No authentication required. Listen to channel: chat.conversation.{stationId}.{clientId} for real-time updates.",
"operationId": "getConversationHistoryAsClient",
"parameters": [
{
"name": "stationId",
"in": "path",
"description": "ID of the station",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "clientId",
"in": "path",
"description": "ID of the client",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "limit",
"in": "query",
"description": "Number of messages to retrieve",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1,
"example": 50
}
}
],
"responses": {
"200": {
"description": "Conversation history retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"properties": {
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"total": {
"type": "integer",
"example": 1
},
"unread_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/v1/chat/conversations/{stationId}/{clientId}/read": {
"post": {
"tags": [
"Chat"
],
"summary": "Mark messages as read as user",
"description": "Mark all messages in a conversation as read. Requires authentication. Real-time notifications are sent to channel: user.{userId}",
"operationId": "markAsReadAsUser",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "stationId",
"in": "path",
"description": "ID of the station",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "clientId",
"in": "path",
"description": "ID of the client",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
}
],
"responses": {
"200": {
"description": "Messages marked as read successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Messages marked as read"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/patient/chat/conversations/{stationId}/{clientId}/read": {
"post": {
"tags": [
"Patient Chat"
],
"summary": "Mark messages as read as patient",
"description": "Mark all messages in a conversation as read. No authentication required. Real-time notifications are sent to channel: user.{stationId}",
"operationId": "markAsReadAsClient",
"parameters": [
{
"name": "stationId",
"in": "path",
"description": "ID of the station",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "clientId",
"in": "path",
"description": "ID of the client",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
}
],
"responses": {
"200": {
"description": "Messages marked as read successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Messages marked as read"
}
},
"type": "object"
}
}
}
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/v1/chat/messages/{messageId}": {
"delete": {
"tags": [
"Chat"
],
"summary": "Delete message as user (station provider)",
"description": "Delete a message. Only the specific user who sent the message can delete it. All station users can see all station messages, but only the sender can delete their own messages. Requires authentication. Real-time notifications are sent to channel: chat.conversation.{stationId}.{clientId}",
"operationId": "deleteMessageAsUser",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "messageId",
"in": "path",
"description": "ID of the message to delete",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Message deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Message deleted successfully"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Access denied - only sender can delete message",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Access denied: only the sender can delete their own message"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/patient/chat/messages/{messageId}": {
"delete": {
"tags": [
"Patient Chat"
],
"summary": "Delete message as patient",
"description": "Delete a message. Only the sender can delete their own messages. No authentication required. Real-time notifications are sent to channel: user.{stationId}",
"operationId": "deleteMessageAsClient",
"parameters": [
{
"name": "messageId",
"in": "path",
"description": "ID of the message to delete",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Client ID for verification",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_id"
],
"properties": {
"client_id": {
"description": "ID of the client",
"type": "integer",
"example": 456
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Message deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Message deleted successfully"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Access denied - only sender can delete message",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Access denied: only sender can delete message"
}
},
"type": "object"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/v1/chat/conversations": {
"get": {
"tags": [
"Chat"
],
"summary": "Get user conversations (station provider)",
"description": "Get all conversations for stations the authenticated user has access to. All station users can see all station messages, but only the sender can delete their own messages. Requires authentication. Listen to channel: chat.conversation.{stationId}.{clientId} for real-time updates.",
"operationId": "getUserConversations",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Conversations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Conversation"
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/patient/chat/conversations/{clientId}": {
"get": {
"tags": [
"Patient Chat"
],
"summary": "Get patient conversations",
"description": "Get all conversations for a specific client. No authentication required. Listen to channel: user.{stationId} for real-time updates.",
"operationId": "getClientConversations",
"parameters": [
{
"name": "clientId",
"in": "path",
"description": "ID of the client",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
}
],
"responses": {
"200": {
"description": "Conversations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Conversation"
}
}
},
"type": "object"
}
}
}
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/v1/client-api/auth/register": {
"post": {
"tags": [
"Client Authentication"
],
"summary": "Register a new patient user",
"description": "Create a new patient user account and send email verification. Optionally connect to existing patient profile.",
"operationId": "registerClientUser",
"requestBody": {
"description": "Patient registration data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientRegistrationRequest"
}
}
}
},
"responses": {
"201": {
"description": "User created successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "User created successfully"
},
"data": {
"type": "null",
"example": null
}
},
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"email": {
"type": "array",
"items": {
"type": "string",
"example": "The email field is required."
}
},
"password": {
"type": "array",
"items": {
"type": "string",
"example": "The password field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "Email already exists",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Email already exists"
},
"errors": {
"properties": {
"email": {
"type": "array",
"items": {
"type": "string",
"example": "The email has already been taken."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/client-api/auth/login": {
"post": {
"tags": [
"Client Authentication"
],
"summary": "Login patient user",
"description": "Authenticate a patient user and return JWT token with user info and connected patient profiles",
"operationId": "loginClientUser",
"requestBody": {
"description": "Patient login credentials",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientLoginRequest"
}
}
}
},
"responses": {
"200": {
"description": "Login successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientUserLoginResponse"
}
}
}
},
"401": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid credentials"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid email or password"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"email": {
"type": "array",
"items": {
"type": "string",
"example": "The email field is required."
}
},
"password": {
"type": "array",
"items": {
"type": "string",
"example": "The password field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"429": {
"description": "Too many login attempts",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Too many login attempts. Please try again later."
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Account temporarily blocked"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/client-api/auth/verify": {
"post": {
"tags": [
"Client Authentication"
],
"summary": "Verify patient registration",
"description": "Verify patient user's email address using verification token and return JWT token for immediate login",
"operationId": "verifyClientRegistration",
"requestBody": {
"description": "Email verification token",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientVerificationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Email verified successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientUserLoginResponse"
}
}
}
},
"401": {
"description": "Invalid verification token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid verification token"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "The verification token is invalid or expired"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"token": {
"type": "array",
"items": {
"type": "string",
"example": "The token field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "User not found"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "The user associated with this token was not found"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/client-api/auth/info": {
"get": {
"tags": [
"Client Authentication"
],
"summary": "Get authenticated user info",
"description": "Get current authenticated user information and connected client profiles",
"operationId": "getClientUserInfo",
"responses": {
"200": {
"description": "User info retrieved successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "User info retrieved successfully"
},
"data": {
"properties": {
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"email_verified_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"client_profiles": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"client_id": {
"type": "integer",
"example": 1
},
"business_id": {
"type": "integer",
"example": 1
},
"is_active": {
"type": "boolean",
"example": true
},
"business": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Medical"
}
},
"type": "object"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid or missing authentication token"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/client-api/auth/login/temp": {
"post": {
"tags": [
"Client Authentication"
],
"summary": "Login with temporary token",
"description": "Authenticate user using a temporary token and return user information with client profiles",
"operationId": "clientLoginTemp",
"requestBody": {
"description": "Temporary token for authentication",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Temporary authentication token",
"type": "string",
"example": "temp-token-abc123"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Login successful",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"message": {
"type": "string",
"example": "Welcome back"
},
"data": {
"properties": {
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"email_verified_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"client_profiles": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"client_id": {
"type": "integer",
"example": 1
},
"business_id": {
"type": "integer",
"example": 1
},
"is_active": {
"type": "boolean",
"example": true
},
"business": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Medical"
}
},
"type": "object"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or expired token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid or expired token"
}
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"token": {
"type": "array",
"items": {
"type": "string",
"example": "The token field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "An unexpected error occurred"
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/security/security-options": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get security options for client portal feature",
"description": "Retrieve available security options for a specific client portal feature",
"operationId": "40fb80efbd863afb7b7d86f3766816e1",
"parameters": [
{
"name": "feature_type",
"in": "query",
"description": "The type of client portal feature",
"required": true,
"schema": {
"type": "string",
"enum": [
"schedule_appointment",
"reschedule_appointment",
"domain_verification",
"view_appointment",
"join_waitlist",
"resolve_general_booking_link",
"view_waitlist",
"form_link",
"submit_feedback",
"submit_form_request"
],
"example": "schedule_appointment"
}
},
{
"name": "feature_value",
"in": "query",
"description": "The value associated with the feature (e.g., booking link path, form UUID)",
"required": true,
"schema": {
"type": "string",
"example": "my-booking-link"
}
},
{
"name": "redirect_url",
"in": "query",
"description": "Optional redirect URL after successful validation",
"required": false,
"schema": {
"type": "string",
"format": "url",
"example": "https://example.com/success"
}
},
{
"name": "subdomain",
"in": "query",
"description": "Optional subdomain (domain) to check for business first before using default business resolution. Uses same logic as domain verification.",
"required": false,
"schema": {
"type": "string",
"example": "clinic.example.com"
}
}
],
"responses": {
"200": {
"description": "Security options retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Security options retrieved successfully"
},
"data": {
"properties": {
"display_settings": {
"$ref": "#/components/schemas/DisplaySettings"
},
"security_options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SecurityOption"
}
},
"session": {
"type": "string",
"example": "a1b2c3d4e5f6g7h8"
},
"verification_settings": {
"oneOf": [
{
"$ref": "#/components/schemas/VerificationSettings"
}
],
"nullable": true,
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error or invalid feature",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Feature not found or business not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Feature not found"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/security/validate-session": {
"post": {
"tags": [
"Client Portal"
],
"summary": "Validate patient credentials and create session",
"description": "Validate patient credentials using the provided security method and create a new session upon successful validation. Returns only the session data on success.",
"operationId": "5a27aa9d7c3c9fddc37f84ab3085eee3",
"parameters": [
{
"name": "feature_type",
"in": "query",
"description": "The type of client portal feature",
"required": true,
"schema": {
"type": "string",
"enum": [
"schedule_appointment",
"reschedule_appointment",
"domain_verification",
"view_appointment",
"join_waitlist",
"resolve_general_booking_link",
"view_waitlist",
"form_link",
"submit_feedback",
"submit_form_request"
],
"example": "schedule_appointment"
}
},
{
"name": "feature_value",
"in": "query",
"description": "The value associated with the feature (e.g., booking link path, form UUID)",
"required": true,
"schema": {
"type": "string",
"example": "my-booking-link"
}
},
{
"name": "redirect_url",
"in": "query",
"description": "Optional redirect URL after successful validation",
"required": false,
"schema": {
"type": "string",
"format": "url",
"example": "https://example.com/success"
}
},
{
"name": "subdomain",
"in": "query",
"description": "Optional subdomain (domain) to check for business first before using default business resolution. Uses same logic as domain verification.",
"required": false,
"schema": {
"type": "string",
"example": "clinic.example.com"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"type",
"data"
],
"properties": {
"type": {
"type": "string",
"enum": [
"personal_info",
"validators",
"sso",
"auth_client_id",
"auth_credentials",
"through_invitation"
],
"example": "personal_info"
},
"data": {
"description": "Validation data based on the security type",
"properties": {
"email": {
"type": "string",
"example": "client@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient validated and session created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Client validated and session created successfully"
},
"data": {
"properties": {
"session": {
"description": "Client portal session ID",
"type": "string",
"example": "a1b2c3d4e5f6g7h8"
},
"client": {
"description": "Resolved client information",
"properties": {
"id": {
"type": "integer",
"example": 123
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
}
},
"type": "object",
"nullable": true
},
"resolved": {
"description": "Resolved client ID",
"type": "integer",
"example": 123,
"nullable": true
},
"security": {
"description": "Number of security options applied",
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - validation error or invalid client data",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"type": {
"type": "array",
"items": {
"type": "string",
"example": "The type field is required"
}
},
"data": {
"type": "array",
"items": {
"type": "string",
"example": "The data field is required"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - patient not found or invalid credentials",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Patient not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client blocked or not authorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Client is blocked"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Not found - resource not found or moved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Resource not found or moved"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
}
}
},
"/api/v2/client-api/security/features": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get available client portal features",
"description": "Retrieve list of all available client portal features",
"operationId": "028612d849d21c471eebd8b02c49cb41",
"responses": {
"200": {
"description": "Features retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Features retrieved successfully"
},
"data": {
"properties": {
"features": {
"type": "array",
"items": {
"properties": {
"value": {
"type": "string",
"example": "schedule_appointment"
},
"label": {
"type": "string",
"example": "Schedule Appointment"
},
"requiresUuid": {
"type": "boolean",
"example": false
},
"hasClientId": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
},
"validationTypes": {
"type": "array",
"items": {
"type": "string",
"example": "personal_info"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/security/session-status": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get current session status",
"description": "Retrieve the current client portal session status and information",
"operationId": "7621f21b75cf7670a0afe7d856dc9395",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Session status retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Session status retrieved successfully"
},
"data": {
"properties": {
"featureType": {
"type": "string",
"example": "schedule_appointment"
},
"featureValue": {
"type": "string",
"example": "my-booking-link"
},
"sessionId": {
"type": "string",
"example": "a1b2c3d4e5f6g7h8"
},
"resolvedClient": {
"type": "object",
"example": {
"id": 123,
"name": "John Doe"
},
"nullable": true
},
"securityOptions": {
"description": "Count of security options",
"type": "integer",
"example": 2
},
"securityTypeUsedForValidation": {
"type": "string",
"example": "personal_info",
"nullable": true
},
"has_booking_session": {
"type": "boolean",
"example": true
},
"is_valid": {
"type": "boolean",
"example": true
},
"remaining_minutes": {
"type": "integer",
"example": 25
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Invalid session or missing session header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid session or session not found"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/security/logout": {
"delete": {
"tags": [
"Client Portal"
],
"summary": "Removes the current session",
"description": "Logout from client portal and remove the session",
"operationId": "f42423eafe64e8098628326f7c4a7b37",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Session status retrieved successfully"
}
}
}
},
"/api/v1/client-api/scheduling/slot-booked": {
"post": {
"tags": [
"Client Scheduling"
],
"summary": "Book a slot for appointment",
"description": "Book a specific time slot by selecting location, station, service, and appointment method. This updates the booking session and returns forms and intakes that need to be completed. Requires completed patient validation.",
"operationId": "570cbe6cb49937344a64903786ad97a7",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with completed patient validation",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SlotBookedRequest"
}
}
}
},
"responses": {
"200": {
"description": "Slot booked successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SlotBookedResponse"
}
}
}
},
"400": {
"description": "Bad request - missing or invalid session information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"403": {
"description": "Patient validation required - must complete validate-client first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"422": {
"description": "Validation failed - invalid request data or business logic errors",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/custom-intakes": {
"post": {
"tags": [
"Client Scheduling"
],
"summary": "Save custom intake responses",
"description": "Save responses for custom intake forms. Updates the booking session to mark intakes as submitted. Requires a slot to be booked first.",
"operationId": "a22c81839daea4237540059c08aeacda",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with booked slot",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomIntakesSaveRequest"
}
}
}
},
"responses": {
"200": {
"description": "Custom intakes saved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomIntakesSaveResponse"
}
}
}
},
"400": {
"description": "Bad request - missing session information or incomplete booking",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"403": {
"description": "Slot booking required - must book a slot first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"422": {
"description": "Validation failed - invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/form": {
"post": {
"tags": [
"Client Scheduling"
],
"summary": "Submit form responses",
"description": "Submit responses for the form associated with the current booking. Updates the booking session to mark form as submitted. Requires a slot to be booked first.",
"operationId": "6b4a5336e5847f7ce8c91d271518740b",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with booked slot",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicFormSubmitRequest"
}
}
}
},
"responses": {
"201": {
"description": "Form response created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormSubmitResponse"
}
}
}
},
"400": {
"description": "Bad request - missing session information, incomplete booking, or form ID mismatch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"403": {
"description": "Slot booking required - must book a slot first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"422": {
"description": "Validation failed - invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/booking-completed": {
"post": {
"tags": [
"Client Scheduling"
],
"summary": "Mark booking as completed",
"description": "Check if all required forms and intakes are submitted and mark the booking as completed. If requirements are not met, returns the missing items that need to be completed. Requires a slot to be booked first.",
"operationId": "42249bb893ca2a22010531bea05023e2",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with booked slot",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Booking data required to save the completed booking",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingCompletedRequest"
}
}
}
},
"responses": {
"200": {
"description": "Booking completed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingCompletedResponse"
}
}
}
},
"422": {
"description": "Validation error - forms/intakes not submitted",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"forms": {
"properties": {
"has_form": {
"type": "boolean",
"example": true
},
"form": {
"$ref": "#/components/schemas/FormDetail"
}
},
"type": "object"
},
"intakes": {
"properties": {
"has_intakes": {
"type": "boolean",
"example": true
},
"intakes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomIntakeDetail"
}
}
},
"type": "object"
},
"session": {
"properties": {
"is_slot_booked": {
"type": "boolean",
"example": true
},
"booked_service_id": {
"type": "integer",
"example": 3
},
"appointment_id": {
"type": "string",
"example": "appointment_12345"
},
"booking_type": {
"type": "string",
"example": "schedule"
},
"appointment_date": {
"description": "Optional for waitlist bookings, defaults to now() if not provided",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"status": {
"type": "string",
"enum": [
"pending",
"confirmed"
],
"example": "confirmed"
},
"status_updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "Form submission required"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"403": {
"description": "Slot booking required - must book a slot first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/get-schedule-info": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get schedule information using client session",
"description": "Retrieves comprehensive schedule information using only the client portal session. The path or domain is automatically determined from the session's feature_value. This is a unified endpoint that works for both path-based and domain-based scheduling flows. Optionally accepts a schedule_code parameter to override the session's schedule link.",
"operationId": "c9a9c1ba75936b7c5400b613a627557f",
"parameters": [
{
"name": "through",
"in": "query",
"description": "The channel through which the request is made",
"required": false,
"schema": {
"type": "string",
"enum": [
"web",
"mobile",
"api"
],
"example": "web"
}
},
{
"name": "schedule_code",
"in": "query",
"description": "Optional schedule code to override the session's default schedule link. Must belong to the same business and match client if it has BookingLinkRequestForClient.",
"required": false,
"schema": {
"type": "string",
"example": "appointment-123"
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded) containing the feature_value (path or domain)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50IiwiZmVhdHVyZVZhbHVlIjoiYXBwb2ludG1lbnQtMTIzIn0="
}
}
],
"responses": {
"200": {
"description": "Schedule information retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Schedule resolved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"business_data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Acme Medical Center"
},
"domain": {
"type": "string",
"example": "acme.medcenter.com"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"schedule_code": {
"description": "The resolved schedule link custom path",
"type": "string",
"example": "appointment-123"
},
"owner_type": {
"description": "Type of the schedule owner (business, location, station)",
"type": "string",
"example": "business"
},
"owner_id": {
"description": "ID of the schedule owner",
"type": "integer",
"example": 1
},
"schedule_code_override": {
"description": "Flag indicating if schedule_code parameter was used to override session value",
"type": "boolean",
"example": true
},
"display_settings": {
"properties": {
"theme": {
"type": "string",
"example": "medical"
},
"primary_color": {
"type": "string",
"example": "#007bff"
},
"logo": {
"type": "string",
"example": "https://example.com/logo.png"
}
},
"type": "object"
},
"banners": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Welcome"
},
"message": {
"type": "string",
"example": "Welcome to our booking system"
},
"type": {
"type": "string",
"example": "info"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"locations": {
"description": "Available locations for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetailForScheduling"
}
},
"stations": {
"description": "Available stations/providers for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetailForScheduling"
}
},
"services": {
"description": "Available services for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetailForScheduling"
}
},
"client": {
"description": "Resolved client information",
"properties": {
"id": {
"type": "integer",
"example": 123
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/avatar.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"execution_data": {
"description": "Automation execution data if any automations were triggered",
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - invalid through parameter or missing feature_value in session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"through": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid through parameter"
}
},
"feature_value": {
"type": "array",
"items": {
"type": "string",
"example": "No path or domain found in session"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client portal session not authorized for this resource",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to access this resource"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Schedule link not found, expired, or inactive",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Schedule link not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/info/{customPath}": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get schedule information by custom path",
"description": "Retrieves comprehensive schedule information for a specific custom path using client portal session. This endpoint requires a valid X-Client-Session header and validates the client portal session before returning schedule data.",
"operationId": "f883cf9deec68f57c7cce7f8c83cd7eb",
"parameters": [
{
"name": "customPath",
"in": "path",
"description": "The custom path identifier for the schedule link",
"required": true,
"schema": {
"type": "string",
"example": "appointment-123"
}
},
{
"name": "through",
"in": "query",
"description": "The channel through which the request is made",
"required": false,
"schema": {
"type": "string",
"enum": [
"web",
"mobile",
"api"
],
"example": "web"
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Schedule information retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Schedule resolved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"business_data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Acme Medical Center"
},
"domain": {
"type": "string",
"example": "acme.medcenter.com"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"schedule_code": {
"description": "The resolved schedule link custom path",
"type": "string",
"example": "appointment-123"
},
"owner_type": {
"description": "Type of the schedule owner (business, location, station)",
"type": "string",
"example": "business"
},
"owner_id": {
"description": "ID of the schedule owner",
"type": "integer",
"example": 1
},
"schedule_code_override": {
"description": "Flag indicating if path parameter was used to override session value",
"type": "boolean",
"example": true
},
"display_settings": {
"properties": {
"theme": {
"type": "string",
"example": "medical"
},
"primary_color": {
"type": "string",
"example": "#007bff"
},
"logo": {
"type": "string",
"example": "https://example.com/logo.png"
}
},
"type": "object"
},
"banners": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Welcome"
},
"message": {
"type": "string",
"example": "Welcome to our booking system"
},
"type": {
"type": "string",
"example": "info"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"locations": {
"description": "Available locations for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetailForScheduling"
}
},
"stations": {
"description": "Available stations/providers for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetailForScheduling"
}
},
"services": {
"description": "Available services for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetailForScheduling"
}
},
"client": {
"description": "Resolved client information",
"properties": {
"id": {
"type": "integer",
"example": 123
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/avatar.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"execution_data": {
"description": "Automation execution data if any automations were triggered",
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - invalid through parameter or client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"through": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid through parameter"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client portal session not authorized for this resource",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to access this resource"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Schedule link not found, expired, or inactive",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Schedule link not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/domain-info/{domain}": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get schedule information by domain",
"description": "Retrieves comprehensive schedule information for a specific domain using client portal session. This endpoint requires a valid X-Client-Session header and validates the client portal session before returning schedule data. Used for domain-based scheduling flows.",
"operationId": "5352347aca680f4f521889b34179794b",
"parameters": [
{
"name": "domain",
"in": "path",
"description": "The business domain to resolve for scheduling",
"required": true,
"schema": {
"type": "string",
"example": "acme.medcenter.com"
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6ImRvbWFpbl92ZXJpZmljYXRpb24ifQ=="
}
}
],
"responses": {
"200": {
"description": "Schedule information retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Schedule resolved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"business_data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Acme Medical Center"
},
"domain": {
"type": "string",
"example": "acme.medcenter.com"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"schedule_code": {
"description": "The resolved schedule link custom path for the domain",
"type": "string",
"example": "acme-medcenter"
},
"owner_type": {
"description": "Type of the schedule owner (business, location, station)",
"type": "string",
"example": "business"
},
"owner_id": {
"description": "ID of the schedule owner",
"type": "integer",
"example": 1
},
"schedule_code_override": {
"description": "Flag indicating if domain parameter was used to override session value",
"type": "boolean",
"example": true
},
"display_settings": {
"properties": {
"theme": {
"type": "string",
"example": "medical"
},
"primary_color": {
"type": "string",
"example": "#007bff"
},
"logo": {
"type": "string",
"example": "https://example.com/logo.png"
}
},
"type": "object"
},
"banners": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Welcome"
},
"message": {
"type": "string",
"example": "Welcome to our booking system"
},
"type": {
"type": "string",
"example": "info"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"locations": {
"description": "Available locations for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetailForScheduling"
}
},
"stations": {
"description": "Available stations/providers for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetailForScheduling"
}
},
"services": {
"description": "Available services for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetailForScheduling"
}
},
"client": {
"description": "Resolved client information",
"properties": {
"id": {
"type": "integer",
"example": 123
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/avatar.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"execution_data": {
"description": "Automation execution data if any automations were triggered",
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client portal session not authorized for this resource",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to access this resource"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Domain not found, schedule link not found, or resource inactive",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Schedule link not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/locations": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get available locations for booking",
"description": "Retrieves all available locations for the current booking session. Requires a valid client portal session and booking session.",
"operationId": "5db1a42d7d01368f79b1245f6f493f77",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations retrieved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetailForScheduling"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client portal session not authorized for this resource",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to access this resource"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Booking session not found or expired",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Booking session not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/stations": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get available stations for booking",
"description": "Retrieves all available stations (providers/staff) for the current booking session. Requires a valid client portal session and booking session.",
"operationId": "9ef7fceb71bb7542693d6ca1a124ccdc",
"parameters": [
{
"name": "location_id",
"in": "query",
"description": "Filter stations by specific location ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Stations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations retrieved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetailForScheduling"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client portal session not authorized for this resource",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to access this resource"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Booking session not found or expired",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Booking session not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/services": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get available services for booking",
"description": "Retrieves all available services for the current booking session. Requires a valid client portal session and booking session.",
"operationId": "1c603303c26ffa2ec8c7fdd7dcfcdff7",
"parameters": [
{
"name": "location_id",
"in": "query",
"description": "Filter services by specific location ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter services by specific station ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services retrieved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetailForScheduling"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - client portal session not authorized for this resource",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You are not authorized to access this resource"
},
"error": {
"type": "string",
"example": "forbidden"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Booking session not found or expired",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Booking session not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/stations/by-ids": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get multiple stations by location station IDs",
"description": "Retrieves details of multiple stations/providers by their location station IDs (pivot table IDs) for the current booking session. Requires a valid client portal session and booking session.",
"operationId": "647359cbf0a0dc15cb16175a35cb6e1b",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "Comma-separated list of location station IDs to retrieve (e.g., '1,2,3')",
"required": true,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Stations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetailForScheduling"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - invalid or missing IDs parameter",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/scheduling/services/by-ids": {
"get": {
"tags": [
"Client Portal"
],
"summary": "Get multiple services by IDs",
"description": "Retrieves details of multiple services by their IDs for the current booking session. Requires a valid client portal session and booking session.",
"operationId": "93dc479efee5f1c6d0eab0a59030e367",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "Comma-separated list of service IDs to retrieve (e.g., '1,2,3')",
"required": true,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services retrieved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetailForScheduling"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - invalid or missing IDs parameter",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing client portal session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid client portal session header"
},
"error": {
"type": "string",
"example": "unauthenticated"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/resolve-domain/{domain}": {
"get": {
"tags": [
"Client Scheduling"
],
"summary": "Resolve domain for scheduling",
"description": "Resolves a business domain to get basic scheduling information. This is typically the first step in the booking flow to identify the business and validate the domain.",
"operationId": "4950007ba83ee9981a8ca05dba522950",
"parameters": [
{
"name": "domain",
"in": "path",
"description": "The business domain to resolve",
"required": true,
"schema": {
"type": "string",
"example": "acme.medcenter.com"
}
}
],
"responses": {
"200": {
"description": "Domain resolved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DomainResolveResponse"
}
}
}
},
"404": {
"description": "Domain not found or inactive",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Domain not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/schedule/{customPath}": {
"get": {
"tags": [
"Client Scheduling"
],
"summary": "Get schedule data by custom path",
"description": "Retrieves comprehensive schedule data for a specific custom path. This includes business information, security options, display settings, and available resources. Creates a new booking session for the client.",
"operationId": "900a0cecc36346798d2275eeff3c7012",
"parameters": [
{
"name": "customPath",
"in": "path",
"description": "The custom path identifier for the schedule link",
"required": true,
"schema": {
"type": "string",
"example": "appointment-123"
}
},
{
"name": "through",
"in": "query",
"description": "The channel through which the request is made",
"required": false,
"schema": {
"type": "string",
"enum": [
"web",
"mobile",
"api"
],
"example": "web"
}
}
],
"responses": {
"200": {
"description": "Schedule data retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleDataResponse"
}
}
}
},
"400": {
"description": "Bad request - invalid through parameter",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"through": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid through parameter"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Schedule link not found, expired, or inactive",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Schedule link not found"
},
"error": {
"type": "string",
"example": "not_found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/validate-client": {
"post": {
"tags": [
"Client Scheduling"
],
"summary": "Validate patient credentials",
"description": "Validates patient credentials and triggers patient validation automation. This endpoint authenticates the patient and may apply business rules that restrict available locations, services, or stations based on automation results.",
"operationId": "4f6a4b6a2343f5d4d88dd52fb84ee301",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier from getScheduleData",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientValidationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Patient validated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientValidationResponse"
}
}
}
},
"400": {
"description": "Bad request - missing or invalid session information",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"type": {
"type": "array",
"items": {
"type": "string",
"example": "The type field is required"
}
},
"value": {
"type": "array",
"items": {
"type": "string",
"example": "The value field is required"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Patient validation failed - invalid credentials or not allowed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Patient not allowed"
},
"error": {
"type": "string",
"example": "unauthorized"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/services": {
"get": {
"tags": [
"Client Scheduling"
],
"summary": "Get available services",
"description": "Retrieves available services based on the current booking session context. Services are filtered based on location, station, and any automation restrictions applied during patient validation. Supports pagination with customizable page sizes.",
"operationId": "ff9acb630410d3e734d4a84dd7a672d9",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with validated patient",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter services by specific location",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter services by specific station (requires location_id)",
"required": false,
"schema": {
"type": "integer",
"example": 2
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination (default: 1)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (default: 10, takes precedence over page_limit)",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "page_limit",
"in": "query",
"description": "Alternative parameter for items per page (fallback if per_page not provided)",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort results by (default: name)",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"duration",
"price"
],
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (default: asc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetail"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 75
},
"count": {
"type": "integer",
"example": 10
},
"per_page": {
"type": "integer",
"example": 10
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 8
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - invalid parameters or missing location for station",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingErrorResponse"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/locations": {
"get": {
"tags": [
"Client Scheduling"
],
"summary": "Get available locations",
"description": "Retrieves available locations based on the current booking session context. Locations are filtered based on service selection and any automation restrictions applied during patient validation. Supports pagination with customizable page sizes.",
"operationId": "498726b540b1ebcdca81b71289601ac5",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with validated patient",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter locations by specific service",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination (default: 1)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (default: 10, takes precedence over page_limit)",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "page_limit",
"in": "query",
"description": "Alternative parameter for items per page (fallback if per_page not provided)",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort results by (default: name)",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"city",
"state"
],
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (default: asc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 100
},
"count": {
"type": "integer",
"example": 10
},
"per_page": {
"type": "integer",
"example": 10
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 10
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - invalid parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingErrorResponse"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/stations": {
"get": {
"tags": [
"Client Scheduling"
],
"summary": "Get available stations",
"description": "Retrieves available stations (providers) based on the current booking session context. Stations are filtered based on location, service selection, and any automation restrictions applied during patient validation. Supports pagination with customizable page sizes.",
"operationId": "a4085ea0a2267c727c569bdb74eb69c2",
"parameters": [
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier with validated patient",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter stations by specific service",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter stations by specific location",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination (default: 1)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (default: 10, takes precedence over page_limit)",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "page_limit",
"in": "query",
"description": "Alternative parameter for items per page (fallback if per_page not provided)",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort results by (default: name)",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"title"
],
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (default: asc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Stations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetail"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 10
},
"per_page": {
"type": "integer",
"example": 10
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 5
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - missing location or invalid parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingErrorResponse"
}
}
}
},
"401": {
"description": "Invalid or expired booking session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerErrorResponse"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/scheduling/test": {
"get": {
"tags": [
"Client Scheduling"
],
"summary": "Test endpoint for development",
"description": "Development test endpoint for debugging purposes. This endpoint should not be used in production.",
"operationId": "9abfcde604a58c04ca289a47a78b9683",
"responses": {
"200": {
"description": "Test data retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Test endpoint working"
},
"data": {
"properties": {
"business": {
"type": "object",
"nullable": true
},
"location": {
"type": "object",
"nullable": true
},
"location_station": {
"type": "object",
"nullable": true
},
"service": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": []
}
},
"/api/v2/client-api/booking/info/{path}": {
"get": {
"tags": [
"Client Booking"
],
"summary": "Resolve booking information",
"description": "Resolve booking link information and initialize booking session. This is the first step in the booking flow.",
"operationId": "d56cf2763e3010eaf921ccb91edcd99b",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier (optional for this endpoint)",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "path",
"in": "path",
"description": "Booking path identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "through",
"in": "query",
"description": "Through parameter for link resolution",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "booking_type",
"in": "query",
"description": "Specific booking type to resolve",
"required": false,
"schema": {
"type": "string",
"enum": [
"GENERAL",
"WALK_IN",
"SCHEDULE"
]
}
}
],
"responses": {
"200": {
"description": "Booking information resolved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingInfoResponse"
}
}
}
},
"404": {
"description": "Booking link not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingInfoErrorResponse"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/locations": {
"get": {
"tags": [
"Client Booking"
],
"summary": "Get available locations",
"description": "Retrieve paginated list of available locations for booking based on session constraints",
"operationId": "60e701e935959931c75b02b5a2e7c3d3",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by service ID",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations retrieved successfully"
},
"data": {
"properties": {
"locations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"locations_meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 10
},
"count": {
"type": "integer",
"example": 5
},
"per_page": {
"type": "integer",
"example": 5
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/stations": {
"get": {
"tags": [
"Client Booking"
],
"summary": "Get available providers/stations",
"description": "Retrieve paginated list of available providers/stations for booking based on session constraints",
"operationId": "bb5be3e435000dfa8777047c3dc2cdd1",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by service ID",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by location ID",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Providers retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations retrieved successfully"
},
"data": {
"properties": {
"stations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetail"
}
},
"stations_meta": {
"properties": {
"pagination": {
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/services": {
"get": {
"tags": [
"Client Booking"
],
"summary": "Get available services",
"description": "Retrieve paginated list of available services for booking based on session constraints",
"operationId": "d6e0e7a13373b3a70f57aa1b1945f8e0",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by location ID",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "location_station_id",
"in": "query",
"description": "Filter by location station ID",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services retrieved successfully"
},
"data": {
"properties": {
"services": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetail"
}
},
"services_meta": {
"properties": {
"pagination": {
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/get-join-status": {
"post": {
"tags": [
"Client Booking"
],
"summary": "Get walk-in join information",
"description": "Get estimated wait time and position for walk-in booking",
"operationId": "3c145e2bc6c529764441db175203befb",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookSlotRequest"
}
}
}
},
"responses": {
"200": {
"description": "Walk-in join information retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalkInJoinInfoResponse"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/book-slot": {
"post": {
"tags": [
"Client Booking"
],
"summary": "Book a time slot",
"description": "Book a specific time slot for walk-in or scheduled appointment",
"operationId": "a3a6a0fd683ffb9a393a245ba54f3490",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookSlotRequest"
}
}
}
},
"responses": {
"200": {
"description": "Slot booked successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingSlotResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingInfoErrorResponse"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/submit-intake": {
"get": {
"tags": [
"Client Booking"
],
"summary": "Submit intake forms",
"description": "Submit custom intake forms for booking",
"operationId": "18e1a0eb5a4db3da5eb2af08ddae4e60",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitIntakeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Intakes submitted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Intakes saved successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingInfoErrorResponse"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/submit-form": {
"get": {
"tags": [
"Client Booking"
],
"summary": "Submit form",
"description": "Submit booking form",
"operationId": "7ed9303836dc186464a7a914f1d39e71",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitFormRequest"
}
}
}
},
"responses": {
"200": {
"description": "Form submitted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form submitted successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicBookingInfoErrorResponse"
}
}
}
}
}
}
},
"/api/v2/client-api/booking/booking-completed": {
"put": {
"tags": [
"Client Booking"
],
"summary": "Complete booking",
"description": "Finalize and complete the booking process",
"operationId": "80885e234355315619e1ccdc6e573496",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client session identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompleteBookingRequest"
}
}
}
},
"responses": {
"200": {
"description": "Booking completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking completed successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/client-api/feedback-forms/send": {
"post": {
"tags": [
"Client Feedback Forms"
],
"summary": "Send feedback form to patient",
"description": "Create and send a feedback form to a client for a specific booking. Validates business relationships and creates a feedback form instance.",
"operationId": "3ff39b51f07af530b8b47f6b9ed7627d",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendFeedbackFormRequest"
}
}
}
},
"responses": {
"201": {
"description": "Feedback form created and sent successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeedbackFormCreatedResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/feedback-forms/{uuid}": {
"get": {
"tags": [
"Client Feedback Forms"
],
"summary": "Get feedback form by UUID",
"description": "Retrieve a feedback form using its UUID. Returns the form with all associated data including sections and fields.",
"operationId": "ede89f6358e09016a4d448831d50baa1",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Feedback form UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
],
"responses": {
"200": {
"description": "Feedback form retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeedbackFormRetrievedResponse"
}
}
}
},
"404": {
"description": "Feedback form not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": []
}
},
"/api/v1/client-api/feedback-forms/{uuid}/submit": {
"post": {
"tags": [
"Client Feedback Forms"
],
"summary": "Submit feedback form responses",
"description": "Submit responses for a feedback form. Validates field responses, transforms values, and marks the form as submitted. Cannot submit if already submitted.",
"operationId": "824898093d793b7e14ff3b317c5f52ac",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Feedback form UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitFeedbackFormRequest"
}
}
}
},
"responses": {
"201": {
"description": "Feedback form submitted successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeedbackFormSubmittedResponse"
}
}
}
},
"404": {
"description": "Feedback form not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"409": {
"description": "Feedback already submitted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConflictResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": []
}
},
"/api/v3/client-api/session/booking/{sessionId}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get booking session status",
"operationId": "027ecafb1f32b6c4ee86fd41408029e5",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "sessionId",
"in": "path",
"description": "Booking session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Booking session status",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking session status"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "active"
},
"expires_at": {
"type": "string",
"example": "2026-02-08T18:30:00Z",
"nullable": true
},
"remaining_minutes": {
"type": "integer",
"example": 18,
"nullable": true
},
"session": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Session not found"
}
}
}
},
"/api/v3/client-api/session/slot/{sessionId}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get slot session status",
"operationId": "e3c2ebe326c5ef809b4f157f416a10c8",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "sessionId",
"in": "path",
"description": "Booking session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Slot session status",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Slot session status"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "missing"
},
"expires_at": {
"type": "string",
"example": "2026-02-08T18:30:00Z",
"nullable": true
},
"remaining_minutes": {
"type": "integer",
"example": 18,
"nullable": true
},
"session": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Session not found"
}
}
}
},
"/api/v3/client-api/session/client/{sessionId}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get client session status",
"operationId": "bdba1bed80ea79ed3b8114d869f0a5e9",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "sessionId",
"in": "path",
"description": "Client session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Client session status",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Client session status"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "active"
},
"expires_at": {
"type": "string",
"example": "2026-02-08T18:30:00Z",
"nullable": true
},
"remaining_minutes": {
"type": "integer",
"example": 18,
"nullable": true
},
"session": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Session not found"
}
}
}
},
"/api/v3/client-api/session/booking/extend": {
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Extend booking session TTL",
"operationId": "04b38a718fb696388157b3575663ffeb",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Booking session extended",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking session extended"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "active"
},
"expires_at": {
"type": "string",
"example": "2026-02-08T18:30:00Z",
"nullable": true
},
"remaining_minutes": {
"type": "integer",
"example": 18,
"nullable": true
},
"session": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v3/client-api/session/slot/extend": {
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Extend slot session TTL",
"operationId": "d61aae3c9442793955018cde3109814b",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Slot session extended",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Slot session extended"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "active"
},
"expires_at": {
"type": "string",
"example": "2026-02-08T18:30:00Z",
"nullable": true
},
"remaining_minutes": {
"type": "integer",
"example": 18,
"nullable": true
},
"session": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v3/client-api/session/client/extend": {
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Extend client session TTL",
"operationId": "7ebce8e66bcbe4c79e7c3e1afb913fad",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Client session extended",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Client session extended"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "active"
},
"expires_at": {
"type": "string",
"example": "2026-02-08T18:30:00Z",
"nullable": true
},
"remaining_minutes": {
"type": "integer",
"example": 18,
"nullable": true
},
"session": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v3/client-api/session/booking": {
"delete": {
"tags": [
"Client Booking V3"
],
"summary": "Cancel booking session",
"operationId": "b1f3087aef55a9ed91fb08a8be8812d9",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Booking session cancelled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking Session cancelled successfully"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
},
"404": {
"description": "Booking session not found"
}
}
}
},
"/api/v3/client-api/session/slot": {
"delete": {
"tags": [
"Client Booking V3"
],
"summary": "Cancel slot session",
"description": "Cancels the slot session and cleans up associated form responses and intake responses. The booking session remains active.",
"operationId": "08b2e27f1eed4a71f99c41fbb1f13e94",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Slot session cancelled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Slot cancelled successfully"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
},
"404": {
"description": "Booking session not found"
}
}
}
},
"/api/v3/client-api/booking/{bookingCode}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Initialize booking session",
"description": "Validates booking link and creates a new booking session for the client. This is the entry point for the booking flow.",
"operationId": "getBookingInfo",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
},
{
"name": "bookingCode",
"in": "path",
"description": "Booking link code (custom path from schedule link)",
"required": true,
"schema": {
"type": "string",
"example": "downtown-clinic"
}
},
{
"name": "through",
"in": "query",
"description": "How the booking link was accessed",
"required": false,
"schema": {
"type": "string",
"default": "link",
"enum": [
"link",
"qr",
"online"
]
}
},
{
"name": "type",
"in": "query",
"description": "If booking type or path is known",
"required": false,
"schema": {
"type": "string",
"enum": [
"walk_in",
"general",
"schedule"
]
}
}
],
"responses": {
"200": {
"description": "Booking session created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Link resolved successfully"
},
"data": {
"properties": {
"session": {
"description": "Session token for subsequent requests",
"type": "string",
"example": "abc123xyz"
},
"booking_type": {
"type": "string",
"enum": [
"general",
"schedule",
"walk_in"
],
"example": "schedule"
},
"next_flow": {
"type": "string",
"enum": [
"location_selection",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"referral_form",
"slot_booking",
"booking_type_selection",
"form",
"intakes",
"booking_confirmation"
],
"example": "location_selection"
},
"next_phase": {
"type": "string",
"enum": [
"location_selection",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"referral_form",
"slot_booking",
"booking_type_selection",
"form",
"intakes",
"booking_confirmation"
],
"example": "location_selection"
},
"organization": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Medical Center"
}
},
"type": "object"
},
"owner_type": {
"type": "string",
"enum": [
"Business",
"Location",
"Station",
"Provider"
],
"example": "Business"
},
"owner": {
"description": "Owner entity details based on owner_type",
"type": "object"
},
"display": {
"description": "UI display configuration",
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Booking link not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Booking link not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Access denied or link inactive",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Access denied"
},
"error": {
"type": "string"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v3/client-api/booking/locations": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get available locations for booking",
"description": "Returns paginated list of locations filtered by booking session constraints. Session automatically applies allowed locations, services, and providers.",
"operationId": "getBookingLocations",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token from getInfo endpoint",
"required": true,
"schema": {
"type": "string",
"example": "abc123xyz"
}
},
{
"name": "search",
"in": "query",
"description": "Search term for location name",
"required": false,
"schema": {
"type": "string",
"example": "downtown"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by service ID (overrides session selection)",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Locations paginated"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Clinic"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"total": {
"type": "integer",
"example": 25
},
"per_page": {
"type": "integer",
"example": 15
},
"count": {
"type": "integer",
"example": 15
},
"total_pages": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid or missing booking session"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/providers": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get available providers for booking",
"description": "Returns paginated list of providers (location-station relationships) filtered by booking session constraints. Automatically filters by selected location and/or service.",
"operationId": "getBookingProviders",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token from getInfo endpoint",
"required": true,
"schema": {
"type": "string",
"example": "abc123xyz"
}
},
{
"name": "search",
"in": "query",
"description": "Search term for provider/station name",
"required": false,
"schema": {
"type": "string",
"example": "dr smith"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter providers offering this service",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter providers at this location",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID",
"required": false,
"schema": {
"type": "integer",
"example": 3
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Providers retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Providers paginated"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"location_id": {
"type": "integer",
"example": 5
},
"station_id": {
"type": "integer",
"example": 3
},
"is_active": {
"type": "boolean",
"example": true
},
"location": {
"description": "Location details",
"type": "object"
},
"station": {
"description": "Station details",
"type": "object"
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"total": {
"type": "integer",
"example": 10
},
"per_page": {
"type": "integer",
"example": 15
},
"count": {
"type": "integer",
"example": 15
},
"total_pages": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid or missing booking session"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/providers/{providerId}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get provider details",
"description": "Returns a single provider (location-station) with location and station details.",
"operationId": "getProviderDetails",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "providerId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Provider retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider retrieved"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"location_id": {
"type": "integer",
"example": 5
},
"station_id": {
"type": "integer",
"example": 3
},
"is_active": {
"type": "boolean",
"example": true
},
"location": {
"type": "object"
},
"station": {
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/services": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get available services for booking",
"description": "Returns paginated list of services filtered by booking session constraints. Automatically filters by selected provider and/or location. Returns effective values (time, availability) based on context.",
"operationId": "getBookingServices",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token from getInfo endpoint",
"required": true,
"schema": {
"type": "string",
"example": "abc123xyz"
}
},
{
"name": "search",
"in": "query",
"description": "Search term for service name",
"required": false,
"schema": {
"type": "string",
"example": "checkup"
}
},
{
"name": "provider_id",
"in": "query",
"description": "Filter services offered by this provider",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter services available at this location",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID",
"required": false,
"schema": {
"type": "integer",
"example": 3
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services paginated"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "General Checkup"
},
"description": {
"type": "string",
"example": "Routine health checkup"
},
"time_in_minute": {
"description": "Effective duration based on provider/location",
"type": "integer",
"example": 30
},
"is_available": {
"type": "boolean",
"example": true
},
"is_visible": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"total": {
"type": "integer",
"example": 50
},
"per_page": {
"type": "integer",
"example": 15
},
"count": {
"type": "integer",
"example": 15
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid or missing booking session"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/services/{serviceId}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get detailed information for a specific service",
"description": "Returns complete details for a service including effective values (time, availability, approval) based on selected provider/location context from booking session.",
"operationId": "getServiceDetails",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"description": "Client portal session data (JSON encoded)",
"required": true,
"schema": {
"type": "string",
"example": "eyJzZXNzaW9uSWQiOiJhMWIyYzNkNGU1ZjZnN2g4IiwiZmVhdHVyZSI6InNjaGVkdWxlX2FwcG9pbnRtZW50In0="
}
},
{
"name": "X-Booking-Session",
"in": "header",
"description": "Booking session token from getInfo endpoint",
"required": true,
"schema": {
"type": "string",
"example": "abc123xyz"
}
},
{
"name": "serviceId",
"in": "path",
"description": "Service ID to retrieve details for",
"required": true,
"schema": {
"type": "integer",
"example": 5
}
}
],
"responses": {
"200": {
"description": "Service details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service retrieved"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "General Checkup"
},
"description": {
"type": "string",
"example": "Comprehensive health examination"
},
"time_in_minute": {
"description": "Effective duration for selected provider/location",
"type": "integer",
"example": 30
},
"is_available": {
"description": "Effective availability for selected provider/location",
"type": "boolean",
"example": true
},
"auto_approve": {
"description": "Effective auto-approval setting for selected provider/location",
"type": "boolean",
"example": true
},
"is_visible": {
"type": "boolean",
"example": true
},
"provider_id": {
"description": "Context provider ID if selected in session",
"type": "integer",
"example": 10
},
"location_id": {
"description": "Context location ID if selected in session",
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid or missing booking session"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Service not found or not available in booking context",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Service not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/resolve-selection": {
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Resolve next booking flow step",
"description": "Sets entity selections (location, provider, service, booking_type) on the session and returns the next flow step.",
"operationId": "resolveSelection",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"entity": {
"type": "string",
"enum": [
"location",
"provider",
"service",
"booking_type"
],
"example": "location"
},
"value": {
"description": "Entity ID or booking type value",
"type": "string",
"example": "5"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Next flow step resolved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Next step resolved"
},
"data": {
"properties": {
"next_flow": {
"type": "string",
"enum": [
"location_selection",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"referral_form",
"slot_booking",
"form",
"intakes",
"booking_confirmation",
"booking_type_selection"
]
},
"next_phase": {
"type": "string",
"enum": [
"location_selection",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"referral_form",
"slot_booking",
"form",
"intakes",
"booking_confirmation",
"booking_type_selection"
]
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/time_slots": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get available time slots",
"description": "Returns available time slots from the schedule server based on provider/date filters.",
"operationId": "getTimeSlots",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "provider_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "service_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "date",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
}
],
"responses": {
"200": {
"description": "Time slots retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Time slots retrieved"
},
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/join-status": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get walk-in queue join status",
"description": "Returns queue position, estimated wait time, and capacity info for walk-in bookings.",
"operationId": "getWalkInJoinStatus",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "provider_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "service_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Join status retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Join status retrieved"
},
"data": {
"properties": {
"position": {
"type": "integer",
"nullable": true
},
"estimated_wait_time_in_minutes": {
"type": "integer",
"nullable": true
},
"next_flow": {
"type": "string",
"enum": [
"form",
"intakes",
"booking_confirmation",
"slot_booking",
"booking_type_selection",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"referral_form"
]
},
"next_phase": {
"type": "string",
"enum": [
"form",
"intakes",
"booking_confirmation",
"slot_booking",
"booking_type_selection",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"referral_form"
]
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Unsupported booking type or missing provider/service"
},
"403": {
"description": "Invalid or missing booking session"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/book-slot": {
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Book an appointment slot",
"description": "Creates a slot session with the selected provider, service, appointment method and date. Returns the next flow step (form, intakes, or confirmation).",
"operationId": "bookSlot",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"appointment_method_id"
],
"properties": {
"provider_id": {
"description": "Override provider selection",
"type": "integer",
"example": 10
},
"service_id": {
"description": "Override service selection",
"type": "integer",
"example": 5
},
"appointment_method_id": {
"type": "integer",
"example": 1
},
"booking_date": {
"type": "string",
"format": "date",
"example": "2026-03-15"
},
"slot_id": {
"description": "Optional slot identifier",
"type": "string",
"example": "slot_abc123"
},
"booking_type": {
"description": "Required when current booking type is general",
"type": "string",
"enum": [
"walk_in",
"schedule"
],
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Slot booked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Slot booked"
},
"data": {
"properties": {
"slotInfo": {
"properties": {
"provider_id": {
"type": "integer"
},
"service_id": {
"type": "integer"
},
"appointment_method_id": {
"type": "integer"
},
"booking_date": {
"type": "string",
"format": "date",
"nullable": true
},
"slot_id": {
"type": "string",
"nullable": true
}
},
"type": "object"
},
"next_flow": {
"type": "string",
"enum": [
"form",
"intakes",
"booking_confirmation"
]
},
"next_phase": {
"type": "string",
"enum": [
"form",
"intakes",
"booking_confirmation"
]
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Missing provider or service"
},
"403": {
"description": "Invalid or missing booking session"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/form": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get booking form",
"description": "Returns the form (with sections, fields, and options) associated with the booked provider/service. Returns null data if no form is configured.",
"operationId": "getBookingForm",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Form retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form retrieved"
},
"data": {
"description": "Form detail with sections and fields, or null if no form",
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session / slot not booked"
}
},
"security": [
{
"BookingSession": []
}
]
},
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Submit booking form responses",
"description": "Submits form field responses for the booking. Validates form_id matches the expected form. Runs form automation for redirect data. Marks the form as submitted on the session.",
"operationId": "submitBookingForm",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_id",
"responses"
],
"properties": {
"form_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"responses": {
"type": "array",
"items": {
"properties": {
"field_id": {
"type": "string",
"format": "uuid"
},
"value": {
"type": "string",
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form submitted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form submitted"
},
"data": {
"description": "Form response with optional automation redirect data (null if form skipped)",
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"400": {
"description": "No form configured or form ID mismatch"
},
"403": {
"description": "Invalid or missing booking session / slot not booked"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/intakes": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get booking intakes",
"description": "Returns custom intakes (required and optional) for the current booking context. Intakes are filtered by business, provider, booking type, and client history.",
"operationId": "getBookingIntakes",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Intakes returned",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Intakes Returned"
},
"data": {
"properties": {
"intakes": {
"type": "array",
"items": {
"type": "object"
}
},
"required": {
"description": "Required intake IDs",
"type": "array",
"items": {
"type": "integer"
}
},
"optional": {
"description": "Optional intake IDs",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session / slot not booked"
}
},
"security": [
{
"BookingSession": []
}
]
},
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Submit booking intake responses",
"description": "Submits custom intake responses. Validates option-based intakes (single vs multiple), required intake presence, and option validity. Stores responses via ClientIntakeResponseRepository.",
"operationId": "submitBookingIntakes",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"intakes"
],
"properties": {
"intakes": {
"type": "array",
"items": {
"properties": {
"intake_id": {
"type": "integer",
"example": 1
},
"value": {
"description": "Scalar value or array of option IDs for multi-select intakes"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Intakes saved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Intakes saved"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session / slot not booked"
},
"422": {
"description": "Validation failed - invalid intake values or missing required intakes"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/booking-types": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get allowed booking types",
"description": "Returns allowed booking types for the selected provider. For general links, returns a map of booking types to link paths; otherwise returns a list of allowed types.",
"operationId": "getBookingTypes",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "provider_id",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "location_id",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 3
}
},
{
"name": "station_id",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
}
],
"responses": {
"200": {
"description": "Allowed booking types resolved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking Selection Resolved"
},
"data": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"example": "schedule"
}
},
{
"properties": {
"walk_in": {
"type": "string",
"example": "walk-in-link",
"nullable": true
},
"schedule": {
"type": "string",
"example": "schedule-link",
"nullable": true
}
},
"type": "object"
}
]
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/referral-form/{serviceId}": {
"get": {
"tags": [
"Client Booking V3"
],
"summary": "Get referral form for selected service",
"description": "Returns the referral form for the selected service if available. Requires a valid booking session and a selected service.",
"operationId": "getReferralFormV3",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "serviceId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Referral form retrieved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form retrieved"
},
"data": {
"description": "Referral form detail or null",
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
},
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Submit referral form",
"description": "Submits referral form responses and resolves referral routing. If internal business is the top scorer (or tied), returns next flow to continue booking. If external partner is the top scorer, creates a booking referral and returns next flow as referral_status.",
"operationId": "submitReferralFormV3",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "serviceId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_id",
"responses"
],
"properties": {
"form_id": {
"type": "string",
"format": "uuid"
},
"responses": {
"type": "array",
"items": {
"properties": {
"field_id": {
"type": "string",
"format": "uuid"
},
"value": {
"type": "string",
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral resolved",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral resolved"
},
"data": {
"properties": {
"result": {
"properties": {
"selected_partner_id": {
"type": "integer",
"nullable": true
},
"score_map": {
"type": "object",
"nullable": true
},
"is_internal": {
"type": "boolean",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"booking_referral": {
"oneOf": [
{
"$ref": "#/components/schemas/BookingReferralResource"
}
],
"nullable": true,
"type": "object"
},
"next_flow": {
"type": "string",
"enum": [
"referral_status",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"slot_booking",
"booking_type_selection",
"form",
"intakes",
"booking_confirmation"
]
},
"next_phase": {
"type": "string",
"enum": [
"referral_status",
"provider_selection",
"service_selection",
"provider_and_service_selection",
"slot_booking",
"booking_type_selection",
"form",
"intakes",
"booking_confirmation"
]
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "No referral form configured or form ID mismatch"
},
"403": {
"description": "Invalid or missing booking session"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v3/client-api/booking/complete": {
"post": {
"tags": [
"Client Booking V3"
],
"summary": "Complete booking",
"description": "Finalizes the booking after slot selection and returns booking details.",
"operationId": "completeBookingV3",
"parameters": [
{
"name": "X-Client-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Booking-Session",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"type": "string",
"nullable": true
},
"status": {
"type": "string",
"example": "confirmed",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Booking completed",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking"
},
"data": {
"$ref": "#/components/schemas/PeClientBookingResource"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Invalid or missing booking session / slot not booked"
},
"422": {
"description": "Validation failed"
}
},
"security": [
{
"BookingSession": []
}
]
}
},
"/api/v1/admin/customer-contacts": {
"post": {
"tags": [
"Contact Us"
],
"summary": "Submit a contact us message",
"description": "Handle the incoming request.",
"operationId": "submitContactUsMessage",
"requestBody": {
"description": "Contact Us message payload",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"message",
"email"
],
"properties": {
"name": {
"description": "Name of the person submitting the message",
"type": "string",
"maxLength": 255,
"example": "John Doe"
},
"message": {
"description": "The actual message content",
"type": "string",
"maxLength": 1000,
"example": "I have a question about your services."
},
"organization": {
"description": "Optional: Organization of the person",
"type": "string",
"maxLength": 255,
"example": "Migranium Inc.",
"nullable": true
},
"website_message": {
"description": "Optional: Specific message related to the website form",
"type": "string",
"maxLength": 255,
"example": "General Inquiry",
"nullable": true
},
"subject": {
"description": "Optional: Subject of the message",
"type": "string",
"maxLength": 255,
"example": "Inquiry about pricing",
"nullable": true
},
"email": {
"description": "Email address of the person",
"type": "string",
"format": "email",
"example": "john.doe@example.com"
},
"phone_number": {
"description": "Optional: Phone number of the person",
"type": "string",
"example": "+1-555-123-4567",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Message submitted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "We have recieved your message"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object",
"example": {
"email": [
"The email must be a valid email address."
]
}
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/upload": {
"post": {
"tags": [
"File"
],
"summary": "Upload a file (global)",
"operationId": "ec36a82169d26a1603261e7ef97ecd2d",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"required": [
"file"
],
"properties": {
"file": {
"description": "File to upload",
"type": "string",
"format": "binary"
},
"access": {
"description": "Access level for the file (default: public for authenticated users, restricted for anonymous)",
"type": "string",
"enum": [
"public",
"restricted"
]
},
"disk": {
"description": "Storage disk to use (default: azure)",
"type": "string",
"enum": [
"azure",
"public",
"s3"
]
},
"station_id": {
"description": "Station ID (required for non-authenticated users)",
"type": "integer"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "File uploaded successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "File uploaded successfully"
},
"data": {
"properties": {
"url": {
"type": "string",
"example": "https://storage.azure.com/uploads/filename.png?sv=2020-08-04&ss=b&srt=sco&sp=rwdlacupitfx&se=2025-07-28T15:35:00Z&st=2025-07-28T07:35:00Z&spr=https&sig=..."
},
"path": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "No file uploaded or missing station ID for anonymous users"
},
"404": {
"description": "Station not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/media/{uuid}": {
"get": {
"tags": [
"File"
],
"summary": "Get media information by UUID",
"description": "Get media information by UUID",
"operationId": "50ba4a90353d21837c323ab36c507e15",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Media UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Temporary URL generated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Temporary URL generated successfully"
},
"data": {
"properties": {
"temporary_url": {
"type": "string",
"example": "https://storage.azure.com/uploads/user123/abc123.jpg"
},
"expires_at": {
"type": "string",
"example": "2025-07-28T15:35:00.000000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Media not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Media not found"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Access denied"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms": {
"get": {
"tags": [
"Forms"
],
"summary": "List forms for the organization",
"description": "Retrieve a paginated list of forms belonging to the organization specified in the X-organizationId header. Supports filtering by service, type, and UUID.",
"operationId": "160ed5900aa01553a5e7cc0aa912d173",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve forms for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter forms by single service ID (backward compatibility)",
"required": false,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "service_ids",
"in": "query",
"description": "Filter forms by multiple service IDs (comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,5"
}
},
{
"name": "type",
"in": "query",
"description": "Filter forms by type",
"required": false,
"schema": {
"type": "string",
"enum": [
"intake",
"service",
"feedback",
"referral",
"inquiry"
],
"example": "intake"
}
},
{
"name": "status",
"in": "query",
"description": "Filter forms by status",
"required": false,
"schema": {
"type": "string",
"enum": [
"draft",
"live",
"inactive"
],
"example": "draft"
}
},
{
"name": "search",
"in": "query",
"description": "Search forms by keyword (searches name, description, success message, submit button title)",
"required": false,
"schema": {
"type": "string",
"example": "patient intake"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of forms per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter forms created from this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter forms created up to this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-31"
}
},
{
"name": "uuid",
"in": "query",
"description": "Filter by specific form UUIDs (comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field (name, type, status, created_at, updated_at)",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (asc, desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Paginated list of forms retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "forms retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 50
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"type": "string",
"example": "intake"
},
"status": {
"type": "string",
"example": "live"
},
"services": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "1"
},
"name": {
"type": "string",
"example": "Primary Care Consultation"
},
"description": {
"type": "string",
"example": "Comprehensive healthcare consultation"
}
},
"type": "object"
},
"example": [
{
"id": "1",
"name": "Primary Care Consultation",
"description": "Comprehensive healthcare consultation"
}
]
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "North York Medical Centre"
},
"address": {
"type": "string",
"example": "123 Medical Ave"
},
"city": {
"type": "string",
"example": "Toronto"
},
"state": {
"type": "string",
"example": "ON"
},
"country": {
"type": "string",
"example": "Canada"
}
},
"type": "object"
},
"example": [
{
"id": 1,
"name": "North York Medical Centre",
"address": "123 Medical Ave",
"city": "Toronto",
"state": "ON",
"country": "Canada"
}
],
"nullable": true
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception and check-in area"
}
},
"type": "object"
},
"example": [
{
"id": 1,
"name": "Reception Desk",
"description": "Main reception and check-in area"
}
],
"nullable": true
},
"service_ids": {
"description": "Backward compatibility - use 'services' instead",
"type": "array",
"items": {
"type": "string"
},
"example": [
"1",
"2",
"5"
]
},
"service_id": {
"description": "Backward compatibility - use 'services' instead",
"type": "string",
"example": "5",
"nullable": true
},
"location_ids": {
"description": "Backward compatibility - use 'locations' instead",
"type": "array",
"items": {
"type": "integer"
},
"example": [
3,
7
],
"nullable": true
},
"location_id": {
"description": "Backward compatibility - use 'locations' instead",
"type": "integer",
"example": 3,
"nullable": true
},
"station_ids": {
"description": "Backward compatibility - use 'stations' instead",
"type": "array",
"items": {
"type": "integer"
},
"example": [
4,
8
],
"nullable": true
},
"station_id": {
"description": "Backward compatibility - use 'stations' instead",
"type": "integer",
"example": 4,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Missing organization header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organization header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Forms"
],
"summary": "Create a new form for the organization",
"description": "Create a new form within the organization specified in the X-organizationId header.\n * Supports multiple form types (intake, service, feedback, referral, inquiry) with type-specific configurations.\n * The form will be automatically associated with the organization context and can include sections, fields, and validation rules.",
"operationId": "a25f55775afc35e784ba60e36b1e0b83",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to create the form within",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Comprehensive form creation data with sections, fields, and type-specific configurations",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"type",
"status"
],
"properties": {
"type": {
"description": "Form type - determines available features and validation rules",
"type": "string",
"enum": [
"intake",
"service",
"feedback",
"referral",
"inquiry"
],
"example": "intake"
},
"status": {
"description": "Form status - draft forms can be edited, live forms are active for submissions",
"type": "string",
"enum": [
"draft",
"live",
"inactive"
],
"example": "draft"
},
"name": {
"description": "Human-readable form name",
"type": "string",
"example": "Patient Intake Form"
},
"description": {
"description": "Form description for internal reference",
"type": "string",
"example": "Initial patient information collection form"
},
"success_message": {
"description": "Message displayed after successful form submission",
"type": "string",
"example": "Thank you! Your form has been submitted successfully"
},
"submit_button_title": {
"description": "Text displayed on the form submit button",
"type": "string",
"example": "Submit Application"
},
"block_message": {
"description": "Message displayed when form submissions are blocked",
"type": "string",
"example": "Sorry, this form is currently unavailable."
},
"logo_url": {
"description": "URL to organization logo displayed on form",
"type": "string",
"format": "url",
"example": "https://example.com/logo.png"
},
"banner_url": {
"description": "URL to banner image displayed on form header",
"type": "string",
"format": "url",
"example": "https://example.com/banner.jpg"
},
"service_id": {
"description": "Single service ID (backward compatibility - use service_ids for multiple services)",
"type": "integer",
"example": 5
},
"service_ids": {
"description": "Array of service IDs to attach to the form",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
5
]
},
"location_id": {
"description": "Single location ID (backward compatibility - use location_ids for multiple locations)",
"type": "integer",
"example": 3
},
"location_ids": {
"description": "Array of location IDs to attach to the form",
"type": "array",
"items": {
"type": "integer"
},
"example": [
3,
7,
12
]
},
"station_id": {
"description": "Single station ID (backward compatibility - use station_ids for multiple stations)",
"type": "integer",
"example": 4
},
"station_ids": {
"description": "Array of station IDs to attach to the form",
"type": "array",
"items": {
"type": "integer"
},
"example": [
4,
8,
15
]
},
"collect_rating": {
"description": "Enable rating collection (required for feedback forms)",
"type": "boolean",
"example": true
},
"collect_general_feedback": {
"description": "Enable general feedback text area (required for feedback forms)",
"type": "boolean",
"example": false
},
"general_feedback_title": {
"description": "Title for general feedback section (feedback forms only)",
"type": "string",
"example": "Additional Comments"
},
"is_auto_approve": {
"description": "Auto-approve submissions without review (intake forms only)",
"type": "boolean",
"example": false
},
"validation_fields": {
"description": "Custom validation fields (intake forms only)",
"type": "array",
"items": {
"type": "string"
},
"example": [
"email",
"phone"
]
},
"partner_mappings": {
"description": "Partner-specific field mappings for data integration (key-value object where keys are partner IDs)",
"type": "object",
"example": {
"partner_id_1": {
"field_1": "external_field_1"
}
}
},
"sections": {
"description": "Form sections containing fields and logic (required for non-feedback forms)",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Unique section identifier",
"type": "string",
"example": "section_1"
},
"title": {
"description": "Section title",
"type": "string",
"example": "Personal Information"
},
"description": {
"description": "Section description",
"type": "string",
"example": "Please provide your basic information"
},
"order": {
"description": "Section display order",
"type": "integer",
"example": 1
},
"flow_action": {
"description": "Action after section completion",
"type": "string",
"enum": [
"submit",
"continue",
"block_form"
],
"example": "continue"
},
"flow_target_section_id": {
"description": "Next section ID for continue action",
"type": "string",
"example": "section_2"
},
"fields": {
"description": "Fields within this section",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Unique field identifier",
"type": "string",
"example": "field_1"
},
"type": {
"description": "Field type (text, email, dropdown, etc.)",
"type": "string",
"example": "text"
},
"title": {
"description": "Field label",
"type": "string",
"example": "Full Name"
},
"placeholder": {
"description": "Field placeholder",
"type": "string",
"example": "Enter your full name"
},
"description": {
"description": "Field help text",
"type": "string",
"example": "Your legal first and last name"
},
"required": {
"description": "Whether field is required",
"type": "boolean",
"example": true
},
"order": {
"description": "Field display order within section",
"type": "integer",
"example": 1
},
"options": {
"description": "Options for dropdown, radio, checkbox fields",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "option_1"
},
"value": {
"type": "string",
"example": "yes"
},
"label": {
"type": "string",
"example": "Yes"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Form created successfully with complete form structure",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form created successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"type": "string",
"example": "intake"
},
"status": {
"type": "string",
"example": "draft"
},
"success_message": {
"type": "string",
"example": "Thank you! Your form has been submitted successfully"
},
"submit_button_title": {
"type": "string",
"example": "Submit Application"
},
"block_message": {
"type": "string",
"example": "Sorry, this form is currently unavailable."
},
"logo_url": {
"type": "string",
"example": "https://example.com/logo.png",
"nullable": true
},
"banner_url": {
"type": "string",
"example": "https://example.com/banner.jpg",
"nullable": true
},
"service_ids": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"1",
"2",
"5"
]
},
"service_id": {
"description": "Backward compatibility - first service ID",
"type": "string",
"example": "5",
"nullable": true
},
"location_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
3,
7,
12
]
},
"location_id": {
"description": "Backward compatibility - first location ID",
"type": "integer",
"example": 3,
"nullable": true
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
4,
8,
15
]
},
"station_id": {
"description": "Backward compatibility - first station ID",
"type": "integer",
"example": 4,
"nullable": true
},
"is_auto_approve": {
"type": "boolean",
"example": false,
"nullable": true
},
"validation_fields": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"email",
"phone"
],
"nullable": true
},
"partner_mappings": {
"type": "object",
"example": {
"partner_id_1": {
"field_1": "external_field_1"
}
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error - missing required fields or invalid data",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"type": [
"The type field is required."
],
"sections": [
"The sections field is required when type is not feedback."
],
"collect_rating": [
"The collect rating field is required when type is feedback."
],
"service_id": [
"The service id field is required when type is service and status is live."
],
"service_ids.0": [
"The service_ids.0 must be an integer."
],
"location_ids.*": [
"The location_ids.* must exist in locations table."
],
"station_ids": [
"The station_ids must be an array."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/{form_uuid}": {
"get": {
"tags": [
"Forms"
],
"summary": "Get a single form (with sections, fields, and options)",
"description": "Retrieve a single form by its UUID, including all sections, fields, and options. For inquiry forms, also includes client_info_configs specifying required client attributes. The form will be associated with the organization specified in the X-organizationId header.",
"operationId": "fbd6d84a925bea163e43ee1d0ced17e7",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve the form for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"example": "form_123e4567-e89b-12d3-a456-426614174000"
}
],
"responses": {
"200": {
"description": "Form details with sections, fields, and options retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form retrieved successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"description": "Form type - when 'inquiry', client_info_configs will be included",
"type": "string",
"example": "inquiry"
},
"status": {
"type": "string",
"example": "draft"
},
"description": {
"type": "string",
"example": "Initial patient information collection form"
},
"success_message": {
"type": "string",
"example": "Thank you! Your form has been submitted successfully"
},
"submit_button_title": {
"type": "string",
"example": "Submit Application"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
},
"sections": {
"description": "Form sections with fields and options",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "section_123e4567-e89b-12d3-a456-426614174000"
},
"title": {
"type": "string",
"example": "Personal Information"
},
"description": {
"type": "string",
"example": "Please provide your basic information"
},
"order": {
"type": "integer",
"example": 1
},
"fields": {
"description": "Fields within this section",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "field_123e4567-e89b-12d3-a456-426614174000"
},
"type": {
"type": "string",
"example": "text"
},
"title": {
"type": "string",
"example": "Full Name"
},
"placeholder": {
"type": "string",
"example": "Enter your full name"
},
"required": {
"type": "boolean",
"example": true
},
"order": {
"type": "integer",
"example": 1
},
"options": {
"description": "Available options for select/radio/checkbox fields",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "option_123e4567-e89b-12d3-a456-426614174000"
},
"label": {
"type": "string",
"example": "Male"
},
"value": {
"type": "string",
"example": "male"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"client_info_configs": {
"description": "Client attribute configurations required for inquiry forms. Only present when form type is 'inquiry'.",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Attribute ID",
"type": "integer",
"example": 1
},
"label": {
"description": "Display label for the attribute",
"type": "string",
"example": "First Name"
},
"type": {
"description": "Field type: text, email, phone, number, date, select, radio, checkbox",
"type": "string",
"example": "text"
},
"is_system_field": {
"description": "Whether this is a system field (stored in clients table) or custom attribute",
"type": "boolean",
"example": true
},
"options": {
"description": "Available options for select/radio/checkbox types",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Male"
},
"value": {
"type": "string",
"example": "male"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"import_column_name": {
"description": "Column name used for bulk import matching",
"type": "string",
"example": "first_name"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/FormNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Forms"
],
"summary": "Update a form",
"operationId": "9739baf1c705b737bd455a0fb986981d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Form updated"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Forms"
],
"summary": "Delete a form",
"operationId": "0d8a9cc1ba1b5c1a25537b4e57b34010",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Form deleted"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Forms"
],
"summary": "Partially update a form",
"description": "Update specific fields of a form without requiring all fields.\n * Supports updating form metadata, sections (complete replacement), fields, and options.\n * When updating sections, existing sections will be completely replaced with the provided ones.",
"operationId": "dea780aa6d130db789055c00bb07045c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to update the form for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID",
"required": true,
"schema": {
"type": "string"
},
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
],
"requestBody": {
"description": "Partial form update data - all fields are optional",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialUpdateFormRequest"
}
}
}
},
"responses": {
"200": {
"description": "Form partially updated successfully with complete form structure",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form updated successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Updated Form Name"
},
"type": {
"type": "string",
"example": "intake"
},
"status": {
"type": "string",
"example": "live"
},
"description": {
"type": "string",
"example": "Updated form description"
},
"success_message": {
"type": "string",
"example": "Updated success message"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T12:45:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error or invalid partial update data",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"name": [
"The name field must be a string."
],
"sections.0.title": [
"The section title field is required."
],
"sections.0.fields.0.type": [
"The field type is invalid."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/FormNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/{form_uuid}/duplicate": {
"post": {
"tags": [
"Forms"
],
"summary": "Duplicate a form",
"description": "Create a deep copy of an existing form including all sections, fields, options,\n * visibility conditions, date validations, default configs, and location/station relationships.\n * The duplicated form gets a new UUID, '(Copy)' appended to its name, and draft status.",
"operationId": "0aedf7b9be4151e2946e039137198ce6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "UUID of the form to duplicate",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Form duplicated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form created successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/FormNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/bulk-delete": {
"post": {
"tags": [
"Forms"
],
"summary": "Bulk delete forms",
"operationId": "5c7b5e211b77e5a5a58dc05ddba20082",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"uuids"
],
"properties": {
"uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"9d2b5335-0d2d-4016-8f97-26fe9cc8215f",
"1c3a1e6a-2b5d-4f7a-8d91-9b3a1e6a2b5d"
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Bulk delete completed"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/bulk-update-status": {
"post": {
"tags": [
"Forms"
],
"summary": "Bulk update form status",
"operationId": "52593ce5e4877147d8a459b282b75d1e",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"uuids",
"status"
],
"properties": {
"uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"9d2b5335-0d2d-4016-8f97-26fe9cc8215f",
"1c3a1e6a-2b5d-4f7a-8d91-9b3a1e6a2b5d"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"live",
"inactive"
],
"example": "inactive"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Bulk status update completed"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/create-configs": {
"get": {
"tags": [
"Forms"
],
"summary": "Get all configs needed for form creation (types, field types, operators, flows, etc)",
"operationId": "e5443b268f2cdc02b1296b573b0a6bd0",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve forms for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Form creation configs returned",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"properties": {
"form_types": {
"type": "array",
"items": {
"type": "string",
"example": "service"
}
},
"allowed_field_types_by_form_type": {
"type": "object",
"example": {
"service": [
"text",
"number",
"dropdown"
],
"feedback": [
"text",
"scale_1_10"
]
}
},
"field_types": {
"type": "object",
"example": {
"text": {
"label": "Text Input",
"category": "basic",
"operators": [
"equals",
"contains"
]
},
"number": {
"label": "Number",
"category": "basic",
"operators": [
"number_equals",
"gt"
]
}
}
},
"field_operators": {
"type": "object",
"example": {
"equals": {
"label": "is exactly",
"value_type": "string"
},
"gt": {
"label": "is greater than",
"value_type": "number"
}
}
},
"section_flows": {
"type": "array",
"items": {
"type": "string",
"example": "submit"
}
},
"form_statuses": {
"type": "array",
"items": {
"type": "string",
"example": "draft"
}
},
"form_response_flags": {
"type": "object",
"example": {
"missing_information": {
"label": "Missing Information",
"description": "Indicates that required information is missing from the form response."
},
"needs_review": {
"label": "Needs Review",
"description": "Marks the response for further review by staff or administrators."
}
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-requests": {
"get": {
"tags": [
"Forms"
],
"summary": "List form requests for the organization",
"description": "Retrieve a paginated list of form requests belonging to the organization specified in the X-organizationId header. Form requests represent instances where forms are sent to specific clients with expiration and notification settings.",
"operationId": "d640192df191c96ed082bb8f9c8e1633",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve form requests for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of form requests per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Paginated list of form requests retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form requests retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 25
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FormRequest"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Forms"
],
"summary": "Create a new form request",
"description": "Create a new form request to send a form to specific clients. The form request includes expiration settings, notification preferences, and a list of clients who should receive the form. Email and SMS notifications can be automatically sent to clients.",
"operationId": "7d292d70d59bc5de3367153f1ae44d28",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to create the form request within",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Form request creation data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_id",
"client_ids"
],
"properties": {
"form_id": {
"description": "UUID of the form to send to clients",
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"client_ids": {
"description": "Array of client IDs who should receive the form request",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
},
"message": {
"description": "Optional message to include with the form request",
"type": "string",
"example": "Please complete this form at your earliest convenience.",
"nullable": true
},
"send_email": {
"description": "Whether to send email notifications to clients",
"type": "boolean",
"example": true
},
"send_sms": {
"description": "Whether to send SMS notifications to clients",
"type": "boolean",
"example": false
},
"expire_option": {
"description": "How the form request should expire",
"type": "string",
"enum": [
"never",
"duration",
"specific_date"
],
"example": "duration"
},
"expire_duration": {
"description": "Number of units until expiration (required if expire_option is 'duration')",
"type": "integer",
"example": 7,
"nullable": true
},
"expire_duration_unit": {
"description": "Unit for expiration duration (required if expire_option is 'duration')",
"type": "string",
"enum": [
"days",
"hours",
"weeks",
"months"
],
"example": "days",
"nullable": true
},
"expire_date": {
"description": "Specific expiration date (required if expire_option is 'specific_date')",
"type": "string",
"format": "date",
"example": "2025-02-15",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Form request created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form request created successfully"
},
"data": {
"$ref": "#/components/schemas/FormRequest"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error or missing required fields",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"form_id": [
"The form id field is required."
],
"client_ids": [
"The client ids field is required."
],
"expire_duration": [
"The expire duration field is required when expire option is duration."
],
"expire_date": [
"The expire date field is required when expire option is specific date."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-requests/{form_request_uuid}": {
"get": {
"tags": [
"Forms"
],
"summary": "Get a single form request",
"description": "Retrieve a specific form request by its UUID, including details about the associated form, clients, completion status, and expiration information.",
"operationId": "dabfda6572f2d4472a79b63dfc37e881",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve the form request for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_request_uuid",
"in": "path",
"description": "Form request UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"responses": {
"200": {
"description": "Form request details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form request retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/FormRequest"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/{form_uuid}/locations": {
"get": {
"tags": [
"Forms"
],
"summary": "Get locations and stations configured for a form",
"description": "Retrieve all locations and their associated stations that are configured for a specific form. Returns hierarchical structure with locations containing their stations.",
"operationId": "3928ca2058f548b3d4a5f6026820bfdf",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID to retrieve locations for",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"responses": {
"200": {
"description": "Form locations and stations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form locations retrieved successfully"
},
"data": {
"properties": {
"form_uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"form_name": {
"type": "string",
"example": "Patient Intake Form"
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Office"
},
"address": {
"type": "string",
"example": "123 Main Street"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"country": {
"type": "string",
"example": "USA"
},
"phone_number": {
"type": "string",
"example": "+1-555-0123"
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception area"
},
"image": {
"type": "string",
"example": "https://example.com/station.jpg",
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses": {
"get": {
"tags": [
"FormResponses"
],
"summary": "List form responses with advanced filtering",
"description": "Retrieve a paginated list of form responses with comprehensive filtering options matching the UI interface.",
"operationId": "0550d38d51b1e0f68c7ace930dcce32d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve form responses for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "location_ids[]",
"in": "query",
"description": "Filter by locations (e.g., North York Medical)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
{
"name": "form_types[]",
"in": "query",
"description": "Filter by form types",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"intake",
"service",
"feedback",
"referral",
"inquiry"
],
"example": "service"
}
}
},
{
"name": "form_statuses[]",
"in": "query",
"description": "Filter by form statuses (e.g., Live, Draft, Unpublished)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"draft",
"live",
"unpublished"
],
"example": "live"
}
}
},
{
"name": "statuses[]",
"in": "query",
"description": "Filter by form response statuses (e.g., Pending, Completed)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"pending",
"completed",
"blocked",
"approved",
"declined"
],
"example": "pending"
}
}
},
{
"name": "flags[]",
"in": "query",
"description": "Filter by flags (e.g., Urgent Attention)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"urgent_attention",
"follow_up",
"high_priority",
"requires_review"
],
"example": "urgent_attention"
}
}
},
{
"name": "station_ids[]",
"in": "query",
"description": "Filter by providers/stations (e.g., Dr. Samuel Johnson)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
{
"name": "service_ids[]",
"in": "query",
"description": "Filter by services (e.g., General Consultation, Blood Test)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
{
"name": "client_ids[]",
"in": "query",
"description": "Filter by patients/clients ('All' for no filter)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
{
"name": "date_from",
"in": "query",
"description": "Start date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "End date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-07-25"
}
},
{
"name": "search",
"in": "query",
"description": "Search term for patient name, form content, or reference",
"required": false,
"schema": {
"type": "string",
"example": "John"
}
}
],
"responses": {
"200": {
"description": "Paginated list of form responses retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form responses retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 25
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "John Smith"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Smith"
},
"email": {
"type": "string",
"example": "john.smith@example.com"
},
"phone_number": {
"type": "string",
"example": "+1-416-555-0123"
}
},
"type": "object",
"nullable": true
},
"service": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Primary Care Consultation"
},
"description": {
"type": "string",
"example": "Comprehensive healthcare consultation"
}
},
"type": "object",
"nullable": true
},
"location": {
"properties": {
"id": {
"type": "integer",
"example": 3
},
"name": {
"type": "string",
"example": "North York Medical Centre"
},
"address": {
"type": "string",
"example": "123 Medical Ave"
},
"city": {
"type": "string",
"example": "Toronto"
},
"state": {
"type": "string",
"example": "ON"
},
"country": {
"type": "string",
"example": "Canada"
}
},
"type": "object",
"nullable": true
},
"station": {
"properties": {
"id": {
"type": "integer",
"example": 4
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception and check-in area"
}
},
"type": "object",
"nullable": true
},
"customer_id": {
"description": "Backward compatibility - use 'client' instead",
"type": "integer",
"example": 123
},
"station_id": {
"description": "Backward compatibility - use 'station' instead",
"type": "integer",
"example": 4
},
"location_id": {
"description": "Backward compatibility - use 'location' instead",
"type": "integer",
"example": 3
},
"service_id": {
"description": "Backward compatibility - use 'service' instead",
"type": "integer",
"example": 5
},
"status": {
"type": "string",
"example": "pending"
},
"submitted_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z",
"nullable": true
},
"created_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
},
"form": {
"properties": {
"id": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"type": "string",
"example": "intake"
}
},
"type": "object"
},
"partner_match_stats": {
"description": "For referral forms only: per-partner match statistics based on partner_mappings",
"type": "array",
"items": {
"properties": {
"partner_id": {
"type": "string",
"example": "21"
},
"match_percentage": {
"type": "number",
"format": "float",
"example": 66.67
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"FormResponses"
],
"summary": "Create a new form response for the organization",
"description": "Create a new form response for a form belonging to the organization specified in the X-organizationId header. The form must exist and belong to the organization.",
"operationId": "d3fc8a69cc135bd81c65fa7f71ed758f",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID for business context",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Form response data with field responses",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreFormResponseRequest"
}
}
}
},
"responses": {
"201": {
"description": "Form response created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form response created successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"form_id": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"session_id": {
"type": "string",
"example": "sess_abc123"
},
"status": {
"type": "string",
"example": "pending"
},
"created_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation Error Response",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"description": "Validation errors grouped by field",
"type": "object",
"example": {
"form_id": [
"Form not found."
],
"responses": [
"Required field 'Full Name' is missing in responses."
],
"responses.0.field_id": [
"Field UUID does not exist in the form definition."
],
"responses.0.value_type": [
"Value type does not match field type."
],
"responses.1.value": [
"Value is not a valid option for field."
],
"client_configs": [
"The client_configs field is required."
],
"client_configs.first_name": [
"The First Name field is required."
],
"client_configs.email": [
"The Email must be a valid email address."
],
"client_configs.phone_number": [
"The Phone Number must be valid."
],
"client_configs.attribute_values.123": [
"The Gender field is required."
],
"client_configs.attribute_values.456": [
"The Age must be a number."
]
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error or missing organization header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"form_id": [
"The form_id field is required."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/{response_uuid}": {
"get": {
"tags": [
"FormResponses"
],
"summary": "Get a single form response from the organization",
"description": "Retrieve detailed information about a specific form response, including all field responses. The response must belong to the organization specified in the X-organizationId header.",
"operationId": "aede26b1d6106eee2c9babf1af028025",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID for business context",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form Response UUID to retrieve",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
}
}
],
"responses": {
"200": {
"description": "Form response details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form response retrieved successfully"
},
"data": {
"properties": {
"id": {
"type": "string",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "John Smith"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Smith"
},
"email": {
"type": "string",
"example": "john.smith@example.com"
},
"phone_number": {
"type": "string",
"example": "+1-416-555-0123"
}
},
"type": "object",
"nullable": true
},
"service": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Primary Care Consultation"
},
"description": {
"type": "string",
"example": "Comprehensive healthcare consultation"
}
},
"type": "object",
"nullable": true
},
"location": {
"properties": {
"id": {
"type": "integer",
"example": 3
},
"name": {
"type": "string",
"example": "North York Medical Centre"
},
"address": {
"type": "string",
"example": "123 Medical Ave"
},
"city": {
"type": "string",
"example": "Toronto"
},
"state": {
"type": "string",
"example": "ON"
},
"country": {
"type": "string",
"example": "Canada"
}
},
"type": "object",
"nullable": true
},
"station": {
"properties": {
"id": {
"type": "integer",
"example": 4
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception and check-in area"
}
},
"type": "object",
"nullable": true
},
"customer_id": {
"description": "Backward compatibility - use 'client' instead",
"type": "integer",
"example": 123
},
"station_id": {
"description": "Backward compatibility - use 'station' instead",
"type": "integer",
"example": 4
},
"location_id": {
"description": "Backward compatibility - use 'location' instead",
"type": "integer",
"example": 3
},
"service_id": {
"description": "Backward compatibility - use 'service' instead",
"type": "integer",
"example": 5
},
"status": {
"type": "string",
"example": "pending"
},
"block_reason": {
"type": "string",
"example": null,
"nullable": true
},
"submitted_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z",
"nullable": true
},
"responses": {
"description": "Organized field responses by sections",
"type": "array",
"items": {
"properties": {
"section_id": {
"type": "string",
"example": "s1e2d3c4-5678-90ab-cdef-1234567890ab"
},
"section_title": {
"type": "string",
"example": "Patient Information"
},
"fields": {
"type": "array",
"items": {
"properties": {
"field_id": {
"type": "string",
"example": "f1e2d3c4-5678-90ab-cdef-1234567890ab"
},
"field_title": {
"type": "string",
"example": "Full Name"
},
"field_type": {
"type": "string",
"example": "text"
},
"raw_value": {
"type": "string",
"example": "John Doe"
},
"display_value": {
"type": "string",
"example": "John Doe"
},
"value_type": {
"type": "string",
"example": "text"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"form": {
"properties": {
"id": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"type": "string",
"example": "intake"
}
},
"type": "object"
},
"partner_match_stats": {
"description": "For referral forms only: per-partner match statistics based on partner_mappings",
"type": "array",
"items": {
"properties": {
"partner_id": {
"type": "string",
"example": "21"
},
"match_percentage": {
"type": "number",
"format": "float",
"example": 66.67
}
},
"type": "object"
}
},
"created_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
},
"updated_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response not found or doesn't belong to organization",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form response not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"FormResponses"
],
"summary": "Update a form response in the organization",
"description": "Update an existing form response that belongs to the organization specified in the X-organizationId header.",
"operationId": "48541e386365f9ce4c439750da5bde92",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID for business context",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form Response UUID to update",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
}
}
],
"requestBody": {
"description": "Updated form response data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateFormResponseRequest"
}
}
}
},
"responses": {
"200": {
"description": "Form response updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form response updated successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"form_id": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"session_id": {
"type": "string",
"example": "sess_abc123"
},
"status": {
"type": "string",
"example": "pending"
},
"updated_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"FormResponses"
],
"summary": "Delete a form response from the organization",
"description": "Delete a form response that belongs to the organization specified in the X-organizationId header.",
"operationId": "5c8985c1ce197e3074b89ff6c7d8180e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID for business context",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form Response UUID to delete",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
}
}
],
"responses": {
"204": {
"description": "Form response deleted successfully"
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/forms/{form_uuid}/responses": {
"get": {
"tags": [
"FormResponses"
],
"summary": "List responses for a specific organization form",
"description": "Retrieve a paginated list of all responses for a specific form that belongs to the organization specified in the X-organizationId header.",
"operationId": "a176d35af280a02402e1cc48e5e6c00f",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID for business context",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID to get responses for",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of responses per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Paginated list of form responses for the specified form",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form responses retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 12
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"session_id": {
"type": "string",
"example": "sess_abc123"
},
"status": {
"type": "string",
"example": "pending"
},
"submitted_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z",
"nullable": true
},
"created_at": {
"type": "string",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form not found or doesn't belong to organization"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/admin-submit": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Admin create a form response on behalf of a client",
"description": "Create a form response as an admin user with admin tracking metadata injected automatically.",
"operationId": "2048ee5f1c576f7951ecd32e9f9f89e3",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_id",
"responses"
],
"properties": {
"form_id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"responses": {
"type": "array",
"items": {
"properties": {
"field_id": {
"type": "string",
"format": "uuid",
"example": "f1e2d3c4-5678-90ab-cdef-1234567890ab"
},
"value": {
"type": "string",
"example": "Sample response value",
"nullable": true
}
},
"type": "object"
}
},
"customer_id": {
"type": "integer",
"example": 123,
"nullable": true
},
"status": {
"type": "string",
"enum": [
"pending",
"completed",
"blocked",
"approved",
"declined"
],
"example": "completed",
"nullable": true
},
"location_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"station_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"service_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"notes": {
"type": "string",
"example": "Admin submitted on behalf of client",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Form response created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form response created successfully"
},
"data": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/mark-types": {
"get": {
"tags": [
"FormResponses"
],
"summary": "Get available mark types",
"description": "Retrieve all available mark types for form responses",
"operationId": "9999e3191007bcf7d13126e73cc539e1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Mark types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Mark types retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"value": {
"type": "string",
"example": "urgent_attention"
},
"label": {
"type": "string",
"example": "Urgent Attention"
},
"color": {
"type": "string",
"example": "red"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/{response_uuid}/mark": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Mark a form response",
"description": "Apply a mark to a form response",
"operationId": "76e4cfaf58070cc77366050ca2d8b093",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form response UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"mark_type": {
"type": "string",
"enum": [
"urgent_attention",
"needs_review",
"missing_information",
"patient_record",
"external_referral",
"reviewed"
],
"example": "urgent_attention"
},
"notes": {
"type": "string",
"example": "Requires immediate attention from medical team",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form response marked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response marked successfully"
},
"data": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "pending"
},
"mark_type": {
"type": "string",
"example": "urgent_attention"
},
"mark_label": {
"type": "string",
"example": "Urgent Attention"
},
"mark_color": {
"type": "string",
"example": "red"
},
"marking_notes": {
"type": "string",
"example": "Requires immediate attention from medical team"
},
"marked_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T10:30:00.000Z"
},
"approval_status": {
"type": "string",
"example": "pending",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T09:00:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"FormResponses"
],
"summary": "Unmark a form response",
"description": "Remove the current mark from a form response, or delete a specific historical mark by mark_id",
"operationId": "0477a2ba1f6589f9f9e95c5208dd32d8",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form response UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"mark_id": {
"description": "Optional historical mark ID to delete. Cannot target the current/latest mark.",
"type": "integer",
"example": 123
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form response unmarked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response unmarked successfully"
},
"data": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "pending"
},
"mark_type": {
"type": "string",
"example": null,
"nullable": true
},
"mark_label": {
"type": "string",
"example": null,
"nullable": true
},
"mark_color": {
"type": "string",
"example": null,
"nullable": true
},
"marking_notes": {
"type": "string",
"example": null,
"nullable": true
},
"marked_at": {
"type": "string",
"example": null,
"nullable": true
},
"approval_status": {
"type": "string",
"example": "pending",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T09:00:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"422": {
"description": "Validation error"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/{response_uuid}/marks": {
"delete": {
"tags": [
"FormResponses"
],
"summary": "Bulk delete historical marks for a form response",
"description": "Delete multiple historical marks from a form response by mark_ids. The current/latest mark cannot be deleted through this endpoint.",
"operationId": "ee6cccdd3b173396139cfcc867870da0",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form response UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"mark_ids"
],
"properties": {
"mark_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
123,
124
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form response marks deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response marks deleted successfully"
},
"data": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"mark_type": {
"type": "string",
"example": "missing_information",
"nullable": true
},
"marked_by": {
"type": "integer",
"example": 4,
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response or mark history entry not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/{response_uuid}/approve": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Approve a form response",
"description": "Approve a form response with optional notes",
"operationId": "2dbb77f73fe8671dc5616559b5c56211",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form response UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"type": "string",
"example": "Approved after review of required documents"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form response approved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response approved successfully"
},
"data": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "approved"
},
"mark_type": {
"type": "string",
"example": "urgent_attention",
"nullable": true
},
"approval_status": {
"type": "string",
"example": "approved"
},
"approval_notes": {
"type": "string",
"example": "All documentation verified and complete"
},
"approved_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T11:15:00.000Z"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T09:00:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/{response_uuid}/reject": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Reject a form response",
"description": "Reject a form response with optional notes",
"operationId": "a04712eace62e4f0e6381a87ea687d25",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "Form response UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"type": "string",
"example": "Missing required documentation"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form response rejected successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response rejected successfully"
},
"data": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "declined"
},
"mark_type": {
"type": "string",
"example": "urgent_attention",
"nullable": true
},
"approval_status": {
"type": "string",
"example": "rejected"
},
"approval_notes": {
"type": "string",
"example": "Missing required identification documents"
},
"approved_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T11:15:00.000Z"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-25T09:00:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/bulk-mark": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Bulk mark form responses",
"description": "Mark multiple form responses with a specific mark type and optional notes. Supports select_all/status/exclude_uuids.",
"operationId": "a1219809c2189601c3f88ce220d48fc6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"mark_type"
],
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"9d2b5335-0d2d-4016-8f97-26fe9cc8215f",
"8c1a4224-0c1c-4015-8e86-15ed8bb7104e"
]
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"mark_type": {
"type": "string",
"example": "urgent_attention"
},
"notes": {
"type": "string",
"example": "Bulk marking for urgent review"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form responses marked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form responses marked successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 2
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/bulk-approve": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Bulk approve form responses",
"description": "Approve multiple form responses with optional notes. Supports select_all/status/exclude_uuids.",
"operationId": "ab046763e7a061cc863bf59d8f46399c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"9d2b5335-0d2d-4016-8f97-26fe9cc8215f",
"8c1a4224-0c1c-4015-8e86-15ed8bb7104e"
]
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"notes": {
"type": "string",
"example": "Bulk approval after review"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form responses approved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form responses approved successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 2
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/bulk-reject": {
"post": {
"tags": [
"FormResponses"
],
"summary": "Bulk reject form responses",
"description": "Reject multiple form responses with optional notes. Supports select_all/status/exclude_uuids.",
"operationId": "a7c80a7c92059ba08016d1ca9d130553",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"9d2b5335-0d2d-4016-8f97-26fe9cc8215f",
"8c1a4224-0c1c-4015-8e86-15ed8bb7104e"
]
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"notes": {
"type": "string",
"example": "Bulk rejection due to incomplete information"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form responses rejected successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form responses rejected successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 2
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/bulk-delete": {
"delete": {
"tags": [
"FormResponses"
],
"summary": "Bulk delete form responses",
"description": "Delete multiple form responses by UUID. Supports select_all/status/exclude_uuids.",
"operationId": "365fdc12baf2f483e7ddad6fae588812",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"9d2b5335-0d2d-4016-8f97-26fe9cc8215f",
"8c1a4224-0c1c-4015-8e86-15ed8bb7104e"
]
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form responses deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form responses deleted successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 2
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/form-responses/{response_uuid}/reports": {
"get": {
"tags": [
"FormResponses",
"Reports"
],
"summary": "List reports for a form response",
"description": "Retrieve all reports attached to a specific form response owned by the authenticated business.",
"operationId": "f681779c9f1f3132f9566413d4fae67e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "UUID of the form response",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"responses": {
"200": {
"description": "Reports retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response reports retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T10:00:00Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid"
},
"404": {
"description": "Form response not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"FormResponses",
"Reports"
],
"summary": "Create a new report for a form response",
"description": "Attach a new report record to a specific form response owned by the authenticated business.",
"operationId": "3abc460e98c28ae6ed7732407945d40d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "response_uuid",
"in": "path",
"description": "UUID of the form response",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"requestBody": {
"description": "Report metadata",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"title",
"file_url"
],
"properties": {
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"type": {
"type": "string",
"example": "imaging",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Report created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response report created successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid"
},
"404": {
"description": "Form response not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}/reports": {
"get": {
"tags": [
"Referrals",
"Reports"
],
"summary": "List reports for a referral",
"description": "Retrieve all reports attached to the form response behind a specific referral. Accessible to either the source or partner business of the referral.",
"operationId": "c560fb456d990a98335880229978fd3f",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral submission",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"responses": {
"200": {
"description": "Reports retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response reports retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T10:00:00Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid"
},
"404": {
"description": "Referral not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Referrals",
"Reports"
],
"summary": "Create a new report for a referral's form response",
"description": "Attach a new report to the form response associated with a referral. Accessible to either the source or partner business of the referral.",
"operationId": "40854a3da2c1ed742d4b458e0e7932c8",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral submission",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"requestBody": {
"description": "Report metadata",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"title",
"file_url"
],
"properties": {
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"type": {
"type": "string",
"example": "imaging",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Report created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response report created successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"type": {
"type": "string",
"example": "imaging",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T10:00:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid"
},
"404": {
"description": "Referral not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/health": {
"get": {
"tags": [
"Health Check"
],
"summary": "Basic health check",
"description": "Check if the API is running and accessible",
"operationId": "healthCheck",
"responses": {
"200": {
"description": "API is healthy",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "healthy"
},
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"version": {
"type": "string",
"example": "1.0.0"
},
"environment": {
"type": "string",
"example": "production"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/health/detailed": {
"get": {
"tags": [
"Health Check"
],
"summary": "Detailed health check",
"description": "Comprehensive health check including database, cache, and external services",
"operationId": "detailedHealthCheck",
"responses": {
"200": {
"description": "Detailed health status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthCheckResponse"
}
}
}
},
"503": {
"description": "Service unavailable - one or more services are unhealthy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthCheckResponse"
}
}
}
}
}
}
},
"/api/health/live": {
"get": {
"tags": [
"Health Check"
],
"summary": "Liveness probe",
"description": "Simple liveness check for Kubernetes/container orchestration",
"operationId": "livenessProbe",
"responses": {
"200": {
"description": "Service is alive",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "alive"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/health/ready": {
"get": {
"tags": [
"Health Check"
],
"summary": "Readiness probe",
"description": "Check if service is ready to handle requests",
"operationId": "readinessProbe",
"responses": {
"200": {
"description": "Service is ready",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "ready"
}
},
"type": "object"
}
}
}
},
"503": {
"description": "Service is not ready",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "not_ready"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/location-stations": {
"get": {
"tags": [
"LocationStation"
],
"summary": "List all location-station relationships for the current organization",
"operationId": "ba3125db0e0962597997b4b9992c8402",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by location ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"message": {
"type": "string",
"example": "Location-Station relationships retrieved successfully"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"LocationStation"
],
"summary": "Attach existing stations to a location",
"description": "Link one or more existing stations to a location that they are not yet assigned to",
"operationId": "3126fffb14d4832a7fceef7ae3d235d7",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids",
"location_id"
],
"properties": {
"station_ids": {
"description": "Array of station IDs to attach",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"location_id": {
"description": "Location ID to attach stations to",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Stations attached to location successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "3 stations attached to location successfully"
},
"data": {
"properties": {
"attached_count": {
"type": "integer",
"example": 3
},
"skipped_count": {
"type": "integer",
"example": 0
},
"attached_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"skipped_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/location-stations/bulk-delete": {
"post": {
"tags": [
"LocationStation"
],
"summary": "Bulk delete location-station relationships",
"description": "Delete multiple location-station relationships by their IDs",
"operationId": "60341ffb64612db0500872b40cbc4e9f",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_station_ids"
],
"properties": {
"location_station_ids": {
"description": "Array of location-station relationship IDs to delete",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Location-station relationships deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 location-station relationships deleted successfully!"
},
"data": {
"properties": {
"deleted_count": {
"type": "integer",
"example": 5
},
"not_found_count": {
"type": "integer",
"example": 0
},
"deleted_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"not_found_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/location-stations/bulk-assign-categories": {
"post": {
"tags": [
"LocationStation"
],
"summary": "Bulk assign location-station relationships to categories",
"description": "Assign multiple location-station relationships to one or more categories",
"operationId": "b81bd3172823274f7f241c91203e1722",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_station_ids",
"category_ids"
],
"properties": {
"location_station_ids": {
"description": "Array of location-station relationship IDs to assign",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"category_ids": {
"description": "Array of category IDs to assign to",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"replace": {
"description": "Whether to replace existing categories or add to them",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Categories assigned successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Categories assigned to 5 location-station relationships successfully!"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/location-stations/bulk-update-status": {
"post": {
"tags": [
"LocationStation"
],
"summary": "Bulk update status of location-station relationships",
"description": "Activate or deactivate multiple location-station relationships",
"operationId": "b18ef997351b1909384e17cb6f5a05d2",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_station_ids",
"is_active"
],
"properties": {
"location_station_ids": {
"description": "Array of location-station relationship IDs to update",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"is_active": {
"description": "Whether to activate or deactivate the location-station relationships",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Location-station statuses updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 location-station relationships activated successfully!"
},
"data": {
"properties": {
"updated_count": {
"type": "integer",
"example": 5
},
"not_found_count": {
"type": "integer",
"example": 0
},
"updated_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"not_found_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/location-stations/{id}/status": {
"put": {
"tags": [
"LocationStation"
],
"summary": "Update status of a single location-station relationship",
"description": "Update the active status of a specific location-station relationship",
"operationId": "bdaf6322672178c329c2b90a51472cf3",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location-Station relationship ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"is_active"
],
"properties": {
"is_active": {
"description": "Whether to activate or deactivate the location-station relationship",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Location-station status updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Location-station relationship status updated successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location-station relationship not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Location-station relationship not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes": {
"get": {
"tags": [
"PatientIntakes"
],
"summary": "List patient intake responses",
"description": "Retrieve a paginated list of patient intake form responses with optional filtering.",
"operationId": "0f434a77e92e4cf4d9ae8a17a7bda72e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "status",
"in": "query",
"description": "Filter by status",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
},
{
"name": "location_ids",
"in": "query",
"description": "Filter by location IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter by station IDs",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "search",
"in": "query",
"description": "Search term",
"required": false,
"schema": {
"type": "string",
"example": "John Doe"
}
},
{
"name": "date_from",
"in": "query",
"description": "Start date filter",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2023-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "End date filter",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2023-12-31"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort field",
"required": false,
"schema": {
"type": "string",
"example": "created_at"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Patient intakes retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intakes retrieved successfully"
},
"data": {
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"meta": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 100
},
"last_page": {
"type": "integer",
"example": 7
}
},
"type": "object"
},
"links": {
"properties": {
"first": {
"type": "string",
"example": "http://example.com/api/v1/patient-intakes?page=1"
},
"last": {
"type": "string",
"example": "http://example.com/api/v1/patient-intakes?page=7"
},
"prev": {
"type": "string",
"example": null,
"nullable": true
},
"next": {
"type": "string",
"example": "http://example.com/api/v1/patient-intakes?page=2"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/{uuid}": {
"get": {
"tags": [
"PatientIntakes"
],
"summary": "Get patient intake detail",
"description": "Retrieve detailed information for a specific patient intake form response.",
"operationId": "ba8bef0e2740a597af257381f6570ee1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"responses": {
"200": {
"description": "Patient intake retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Patient intake not found"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/mark-types": {
"get": {
"tags": [
"PatientIntakes"
],
"summary": "Get patient intake mark types",
"description": "Retrieve available mark types for patient intake responses.",
"operationId": "fc95b7805484af1afcb4f88609c51be9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Mark types retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Mark types retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"value": {
"type": "string",
"example": "urgent_attention"
},
"label": {
"type": "string",
"example": "Urgent Attention"
},
"color": {
"type": "string",
"example": "red"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/counts": {
"get": {
"tags": [
"PatientIntakes"
],
"summary": "Get patient intake status counts",
"description": "Retrieve count of patient intake form responses grouped by status.",
"operationId": "b6874b953605a14d0340082e16eccee8",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Patient intake counts retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake counts retrieved successfully"
},
"data": {
"properties": {
"pending": {
"type": "integer",
"example": 10
},
"approved": {
"type": "integer",
"example": 5
},
"assigned": {
"type": "integer",
"example": 3
},
"rejected": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/{uuid}/mark": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Mark a patient intake",
"description": "Apply a mark to a patient intake response without changing its current status.",
"operationId": "94446221b25a9a0fe18a43b4195ae735",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"mark_type": {
"type": "string",
"enum": [
"urgent_attention",
"needs_review",
"missing_information",
"patient_record",
"external_referral",
"reviewed"
],
"example": "urgent_attention"
},
"notes": {
"type": "string",
"example": "Requires immediate attention from intake team",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intake marked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake marked successfully"
},
"data": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Patient intake not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"PatientIntakes"
],
"summary": "Unmark a patient intake",
"description": "Remove the current mark from a patient intake, or delete a specific historical mark by mark_id.",
"operationId": "f3e33d928b3a8e0457653160f0c3b2d9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"mark_id": {
"description": "Optional historical mark ID to delete. Cannot target the current/latest mark.",
"type": "integer",
"example": 123
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intake unmarked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake unmarked successfully"
},
"data": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Patient intake not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/{uuid}/approve": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Approve patient intake",
"description": "Approve a pending or completed patient intake form response.",
"operationId": "5fb36e9dc2064da9c01925dfced95a97",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"description": "Optional approval notes",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intake approved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake approved successfully"
},
"data": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Patient intake not found"
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/{uuid}/assign": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Assign provider to patient intake",
"description": "Assign a provider station to a patient intake form response.",
"operationId": "232004bf49514ffd6d8e1721cf7cb915",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_id"
],
"properties": {
"station_id": {
"description": "Provider station ID",
"type": "integer",
"example": 123
},
"notes": {
"description": "Optional assignment notes",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Provider assigned successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider assigned successfully"
},
"data": {
"properties": {
"form_response": {
"$ref": "#/components/schemas/FormResponseResource"
},
"emr_result": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient created successfully"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Patient intake not found"
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/{uuid}/retry-emr": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Retry EMR patient creation",
"description": "Retry creating a patient record in the EMR system for a failed sync.",
"operationId": "0bf42864ed4dcd46af05af0985db1e33",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"responses": {
"200": {
"description": "EMR patient creation result",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "EMR patient created successfully"
},
"data": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient created successfully"
},
"patient_id": {
"type": "string",
"example": "EMR12345"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Patient intake not found"
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/{uuid}/reject": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Reject patient intake",
"description": "Reject or decline a patient intake form response.",
"operationId": "95cd74a78c323338750f291912b2d7bf",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "uuid",
"in": "path",
"description": "Patient intake UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"description": "Optional rejection notes",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intake rejected successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient intake rejected successfully"
},
"data": {
"$ref": "#/components/schemas/FormResponseResource"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Patient intake not found"
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/bulk-approve": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Bulk approve patient intake responses",
"description": "Approve multiple intake form responses with optional notes. Supports select_all/status/exclude_uuids.",
"operationId": "ebb1061eec6b90f1beb19ee6790b9e3f",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status when select_all is used",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"notes": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intakes approved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Approved 5 intake(s) successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 5
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/bulk-assign": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Bulk assign provider to patient intakes",
"description": "Assign a provider to multiple intake form responses. Supports select_all/status/exclude_uuids.",
"operationId": "32c27747bd561043eed0c150932dceb0",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status when select_all is used",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_id"
],
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"station_id": {
"type": "integer",
"example": 123
},
"notes": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Providers assigned successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Assigned 5 intake(s) to provider successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 5
},
"failed_count": {
"type": "integer",
"example": 0
},
"emr_success_count": {
"type": "integer",
"example": 4
},
"emr_failed_count": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/bulk-decline": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Bulk decline patient intake responses",
"description": "Decline multiple intake form responses with optional notes. Supports select_all/status/exclude_uuids.",
"operationId": "ad10462e84597acc09215f25c85ef111",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status when select_all is used",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"notes": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intakes declined successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Declined 5 intake(s) successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 5
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/bulk-delete": {
"delete": {
"tags": [
"PatientIntakes"
],
"summary": "Bulk delete patient intake responses",
"description": "Delete multiple intake form responses. Supports select_all/status/exclude_uuids.",
"operationId": "7f7d65fe337b2036fd7f4dffda13b6a0",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status when select_all is used",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"select_all": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Patient intakes deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Deleted 5 intake(s) successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 5
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/patient-intakes/bulk-mark": {
"post": {
"tags": [
"PatientIntakes"
],
"summary": "Bulk mark patient intake responses",
"description": "Mark multiple intake form responses with a mark type and optional notes. Supports select_all/status/exclude_uuids.",
"operationId": "495fe868f7cade9195f34ca21681f362",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "select_all",
"in": "query",
"description": "Apply action to all matching responses",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "status",
"in": "query",
"description": "Filter responses by status when select_all is used",
"required": false,
"schema": {
"type": "string",
"example": "pending"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"mark_type"
],
"properties": {
"response_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"exclude_uuids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"mark_type": {
"type": "string",
"example": "needs_review"
},
"notes": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Form responses marked successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form responses marked successfully"
},
"data": {
"properties": {
"processed_count": {
"type": "integer",
"example": 5
},
"failed_count": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers": {
"get": {
"tags": [
"Providers"
],
"summary": "List providers for the organization",
"description": "Retrieve a paginated list of providers (stations) belonging to the organization specified in the X-organizationId header. Supports filtering, searching, and sorting.",
"operationId": "f5c11f5a21bbbf6cb1be8e94c21bd655",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve providers for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of providers per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "search",
"in": "query",
"description": "Search providers by keyword (searches name, email, phone number)",
"required": false,
"schema": {
"type": "string",
"example": "Dr. Smith"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"email",
"phone_number",
"location_count",
"service_count",
"created_at",
"is_active"
],
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "Paginated list of providers retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "providers retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 50
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProviderBaseResource"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Providers"
],
"summary": "Create a new provider",
"description": "Create a new provider (station) within the organization specified in the X-organizationId header. The provider can be associated with multiple locations.",
"operationId": "ae90ff60b86f9eeec09acb01348bff7c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to create the provider within",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Provider creation data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreProviderRequest"
}
}
}
},
"responses": {
"201": {
"description": "Provider created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider created successfully"
},
"data": {
"$ref": "#/components/schemas/ProviderBaseResource"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error or missing required fields",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"name": [
"The name has already been taken."
],
"email": [
"The email must be a valid email address."
],
"location_ids.0": [
"The selected location_ids.0 is invalid."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/OrganizationNotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}": {
"get": {
"tags": [
"Providers"
],
"summary": "Get a single provider",
"description": "Retrieve a single provider by its ID, including detailed information such as locations, rating, and schedule links.",
"operationId": "405da96d75887ffab017fd2e8fa1a299",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve the provider for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Provider details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/ProviderDetailResource"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingOrganizationHeader"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Providers"
],
"summary": "Update a provider",
"description": "Update an existing provider. All fields are optional for partial updates.",
"operationId": "2d13759fd90a6dbdc9226b79d0350b7e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Provider update data (all fields optional)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProviderRequest"
}
}
}
},
"responses": {
"200": {
"description": "Provider updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider updated successfully"
},
"data": {
"$ref": "#/components/schemas/ProviderBaseResource"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"name": [
"The name has already been taken."
],
"email": [
"The email must be a valid email address."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Providers"
],
"summary": "Delete a provider",
"description": "Delete a provider (station). If X-locationId header is provided, the provider will be detached from that location. If the provider has no remaining locations, it will be completely deleted.",
"operationId": "1a213519240530ed9e21cbc069290775",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID to detach provider from (if provided, only detaches from this location)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Provider deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider deleted successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/forms": {
"get": {
"tags": [
"Providers"
],
"summary": "List forms for a provider",
"description": "Retrieve a paginated list of forms associated with a specific provider. Supports filtering by form type, status, and search.",
"operationId": "060020c0c1455e89cd9a097039bc38f5",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of forms per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 10
}
},
{
"name": "type",
"in": "query",
"description": "Filter forms by type",
"required": false,
"schema": {
"type": "string",
"enum": [
"intake",
"service",
"feedback",
"referral",
"inquiry"
],
"example": "intake"
}
},
{
"name": "status",
"in": "query",
"description": "Filter forms by status",
"required": false,
"schema": {
"type": "string",
"enum": [
"draft",
"live",
"unpublished"
],
"example": "live"
}
},
{
"name": "search",
"in": "query",
"description": "Search forms by keyword",
"required": false,
"schema": {
"type": "string",
"example": "patient intake"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field",
"required": false,
"schema": {
"type": "string",
"enum": [
"location_count",
"submittion_count"
],
"example": "submittion_count"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
}
],
"responses": {
"200": {
"description": "Paginated list of provider forms retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider Forms retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 10
},
"total": {
"type": "integer",
"example": 25
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProviderFormResource"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/forms/{form_uuid}": {
"delete": {
"tags": [
"Providers"
],
"summary": "Remove a form from a provider",
"description": "Remove a form association from a provider. The form will no longer be available for this provider.",
"operationId": "f31f5f2408657f886a1dd2d20f67a666",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "form_uuid",
"in": "path",
"description": "Form UUID",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"responses": {
"200": {
"description": "Form removed from provider successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider Form deleted successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider or form not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/forms/bulk-remove": {
"post": {
"tags": [
"Providers"
],
"summary": "Bulk remove forms from a provider",
"description": "Remove multiple forms from a provider in a single operation.",
"operationId": "6649aa6c818ae24e1334cc28916449dc",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Form UUIDs to remove",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_ids"
],
"properties": {
"form_ids": {
"description": "Array of form UUIDs to remove",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Forms removed from provider successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider Forms deleted successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"form_ids": [
"The form ids field is required."
],
"form_ids.0": [
"The form_ids.0 must be a valid UUID."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/services": {
"get": {
"tags": [
"Providers"
],
"summary": "List services for a provider",
"description": "Retrieve a paginated list of services associated with a specific provider. Includes form count and location count for each service.",
"operationId": "8f0d9fa494a25d2289801d95e0d9a34a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of services per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "search",
"in": "query",
"description": "Search services by name",
"required": false,
"schema": {
"type": "string",
"example": "consultation"
}
}
],
"responses": {
"200": {
"description": "Paginated list of provider services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider services retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 20
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProviderServiceResource"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Providers"
],
"summary": "Add a service to a provider",
"description": "Add or update a service association for a provider. If the service already exists, it will be updated. The service will be available at all locations associated with this provider.",
"operationId": "c99fd5db6ca2c8be8673ee5503db2fa9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Service data to add or update",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"time_in_minute"
],
"properties": {
"name": {
"description": "Service name",
"type": "string",
"example": "Consultation"
},
"description": {
"description": "Service description",
"type": "string",
"example": "General consultation service",
"nullable": true
},
"time_in_minute": {
"description": "Service duration in minutes",
"type": "integer",
"minimum": 1,
"example": 30
},
"is_available": {
"description": "Whether the service is available",
"type": "boolean",
"example": true,
"nullable": true
},
"auto_approve": {
"description": "Whether appointments are auto-approved",
"type": "boolean",
"example": false,
"nullable": true
},
"is_visible": {
"description": "Whether the service is visible to clients",
"type": "boolean",
"example": true,
"nullable": true
},
"appointment_methods": {
"description": "Array of appointment method IDs",
"type": "array",
"items": {
"type": "integer",
"example": 1
},
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Service added or updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service added successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"name": [
"The name field is required."
],
"time_in_minute": [
"The time in minute must be at least 1."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Providers"
],
"summary": "Sync services for a provider",
"description": "Synchronize the services offered by a provider. This will replace any existing service associations with the provided list of service IDs. New services will use default business settings for the provider.",
"operationId": "e915e895ca9c78a9e6b1a0f35327407d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Service IDs to sync",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"ids"
],
"properties": {
"ids": {
"description": "Array of service IDs",
"type": "array",
"items": {
"type": "integer",
"example": 5
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services synced successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider services synced successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/services/{service_id}": {
"put": {
"tags": [
"Providers"
],
"summary": "Update a service for a provider",
"description": "Update service settings (duration, availability, auto-approve, visibility) for a specific service associated with a provider. Updates will apply to all locations where this provider offers the service.",
"operationId": "cd3ebf8c7a7f440c82fc7a3200c38079",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "service_id",
"in": "path",
"description": "Service ID",
"required": true,
"schema": {
"type": "integer",
"example": 5
}
}
],
"requestBody": {
"description": "Service update data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"time_in_minute"
],
"properties": {
"name": {
"description": "Service name",
"type": "string",
"example": "Consultation",
"nullable": true
},
"description": {
"description": "Service description",
"type": "string",
"example": "General consultation service",
"nullable": true
},
"time_in_minute": {
"description": "Service duration in minutes",
"type": "integer",
"minimum": 1,
"example": 45
},
"is_available": {
"description": "Whether the service is available",
"type": "boolean",
"example": true,
"nullable": true
},
"auto_approve": {
"description": "Whether appointments are auto-approved",
"type": "boolean",
"example": false,
"nullable": true
},
"is_visible": {
"description": "Whether the service is visible to clients",
"type": "boolean",
"example": true,
"nullable": true
},
"appointment_methods": {
"description": "Array of appointment method IDs to sync",
"type": "array",
"items": {
"type": "integer",
"example": 1
},
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Service updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service updated successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"time_in_minute": [
"The time in minute must be at least 1."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider or service not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Providers"
],
"summary": "Remove a service from a provider",
"description": "Remove a service association from a provider. The service will no longer be available for this provider.",
"operationId": "bffddeb55076ddcd296aee394bf72e9c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "service_id",
"in": "path",
"description": "Service ID",
"required": true,
"schema": {
"type": "integer",
"example": 5
}
}
],
"responses": {
"200": {
"description": "Service removed from provider successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider Service deleted successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider or service not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/services/bulk-remove": {
"post": {
"tags": [
"Providers"
],
"summary": "Bulk remove services from a provider",
"description": "Remove multiple services from a provider in a single operation.",
"operationId": "39af7e7a50c27c2138fc166ba99f18a1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Service IDs to remove",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids"
],
"properties": {
"service_ids": {
"description": "Array of service IDs to remove",
"type": "array",
"items": {
"type": "integer",
"example": 5
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services removed from provider successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider Services deleted successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"service_ids": [
"The service ids field is required."
],
"service_ids.0": [
"The selected service_ids.0 is invalid."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/services/bulk-update-status": {
"post": {
"tags": [
"Providers"
],
"summary": "Bulk update service auto-approve status",
"description": "Update the auto-approve setting for multiple services associated with a provider in a single operation. This is useful for enabling or disabling auto-approval for multiple services at once.",
"operationId": "71e8a1ee2be24d5361c7018345ebc11d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Service IDs and auto-approve status",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids",
"auto_approve"
],
"properties": {
"service_ids": {
"description": "Array of service IDs to update",
"type": "array",
"items": {
"type": "integer",
"example": 5
},
"minItems": 1
},
"auto_approve": {
"description": "Whether to enable auto-approve for the selected services",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "3 services auto-approve updated successfully for location-station"
},
"data": {
"properties": {
"updated_count": {
"description": "Number of service owner records updated",
"type": "integer",
"example": 3
},
"station_id": {
"description": "Provider (Station) ID",
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"service_ids": [
"The service ids must have at least 1 items."
],
"service_ids.0": [
"The selected service_ids.0 is invalid."
],
"auto_approve": [
"The auto approve field is required."
]
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/referrals": {
"get": {
"tags": [
"Providers"
],
"summary": "List referrals for a provider",
"description": "Retrieve a paginated list of referrals (incoming or outgoing) for a specific provider. Supports filtering by status, date range, and partner business.",
"operationId": "acb024f8dc735d7060caa66148404aef",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "type",
"in": "query",
"description": "Type of referrals to retrieve",
"required": false,
"schema": {
"type": "string",
"default": "incoming",
"enum": [
"incoming",
"outgoing"
],
"example": "incoming"
}
},
{
"name": "status",
"in": "query",
"description": "Filter referrals by status",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"accepted",
"rejected",
"completed",
"auto_declined"
],
"example": "pending"
}
},
{
"name": "source_business_id",
"in": "query",
"description": "Filter incoming referrals by source business ID",
"required": false,
"schema": {
"type": "integer",
"example": 2
}
},
{
"name": "partner_business_id",
"in": "query",
"description": "Filter referrals by partner business ID (alias for source_business_id for incoming, target for outgoing)",
"required": false,
"schema": {
"type": "integer",
"example": 2
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter referrals from this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter referrals up to this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-31"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of referrals per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Paginated list of referrals retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "received referrals retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 30
},
"data": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/ProviderIncomingReferralResource"
},
{
"$ref": "#/components/schemas/ProviderOutgoingReferralResource"
}
]
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Missing organization header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business ID is required for referrals"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/referrals/status-count": {
"get": {
"tags": [
"Providers"
],
"summary": "Get referral status counts for a provider",
"description": "Retrieve a summary of referral status counts (pending, accepted, rejected, etc.) for a specific provider. Supports filtering by date range and partner business.",
"operationId": "43893f102564c3509c2409eaa56a76a0",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "type",
"in": "query",
"description": "Type of referrals to count",
"required": false,
"schema": {
"type": "string",
"default": "incoming",
"enum": [
"incoming",
"outgoing"
],
"example": "incoming"
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter referrals from this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter referrals up to this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-31"
}
},
{
"name": "partner_business_id",
"in": "query",
"description": "Filter referrals by partner business ID",
"required": false,
"schema": {
"type": "integer",
"example": 2
}
}
],
"responses": {
"200": {
"description": "Referral status counts retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral status counts"
},
"data": {
"properties": {
"pending": {
"type": "integer",
"example": 5
},
"accepted": {
"type": "integer",
"example": 10
},
"rejected": {
"type": "integer",
"example": 2
},
"completed": {
"type": "integer",
"example": 8
},
"auto_declined": {
"type": "integer",
"example": 1
},
"total": {
"type": "integer",
"example": 26
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Missing organization header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business ID is required for referrals"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/chat/clients": {
"get": {
"tags": [
"Providers"
],
"summary": "List chat clients for a provider",
"description": "Retrieve a paginated list of clients that have chat conversations with a specific provider. Includes last message, unread count, and online status.",
"operationId": "d1fb42a0fe52875d8c073d40ca8cbd9d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of clients per page",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "Paginated list of chat clients retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider chats retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 25
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProviderClientChatMetaDataResource"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/chat/clients/{client_id}/messages": {
"get": {
"tags": [
"Providers"
],
"summary": "Get chat messages between provider and client",
"description": "Retrieve the conversation history between a provider and a specific client. Messages are returned in chronological order.",
"operationId": "bed38cd5765ab67bd3ae60b0a8040277",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "client_id",
"in": "path",
"description": "Client ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of messages to retrieve",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1,
"example": 50
}
}
],
"responses": {
"200": {
"description": "Chat messages retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Patient chats"
},
"data": {
"properties": {
"messages": {
"description": "Array of chat messages",
"type": "array",
"items": {
"$ref": "#/components/schemas/ProviderClientChatMessage"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized - Patient is not allowed or provider not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Patient is not allowed"
}
},
"type": "object"
}
}
}
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider or client not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/locations": {
"post": {
"tags": [
"Providers"
],
"summary": "Add locations to a provider",
"description": "Add multiple locations to a provider without removing existing associations.",
"operationId": "a91ce0960ccc26f9097d43e814f33a12",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Location IDs to add",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"ids"
],
"properties": {
"ids": {
"description": "Array of location IDs",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Locations added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider locations added successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Providers"
],
"summary": "Remove locations from a provider",
"description": "Remove multiple location associations from a provider.",
"operationId": "4b0b96d82ec9c26d4ec33480ff103734",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Location IDs to remove",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"ids"
],
"properties": {
"ids": {
"description": "Array of location IDs",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Locations removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider locations removed successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Providers"
],
"summary": "Sync locations for a provider",
"description": "Synchronize the locations associated with a provider. This will replace any existing associations with the provided list of location IDs.",
"operationId": "9efe88b9b8f1a669cfe88d3d76620665",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Location IDs to sync",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"ids"
],
"properties": {
"ids": {
"description": "Array of location IDs",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Locations synced successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Provider locations synced successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/providers/{provider_id}/services/bulk-add": {
"post": {
"tags": [
"Providers"
],
"summary": "Add services to a provider",
"description": "Add multiple existing services to a provider without removing existing associations. Services will use default business settings for the provider.",
"operationId": "dc60ed9e8700ab8dbd5ef74ea92d437d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "provider_id",
"in": "path",
"description": "Provider (Station) ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Service IDs to add",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"ids"
],
"properties": {
"ids": {
"description": "Array of service IDs",
"type": "array",
"items": {
"type": "integer",
"example": 5
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "3 services added successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Provider not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/public/forms/{form_path}": {
"get": {
"tags": [
"PublicForms"
],
"summary": "Get a form for public filling",
"description": "Retrieve a form by UUID for public access. No authentication or organization headers required. Only returns live forms.",
"operationId": "fa356d6ba70c451372615e4279f0af7a",
"parameters": [
{
"name": "form_path",
"in": "path",
"description": "Form UUID or link path to retrieve",
"required": true,
"schema": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
},
{
"name": "customer_id",
"in": "query",
"description": "Optional customer ID for pre-filling form data",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "request_id",
"in": "query",
"description": "Optional request identifier for tracking/deep link (e.g., form request client UUID)",
"required": false,
"schema": {
"type": "string",
"example": "14b8fec6-3c9d-4778-a45a-242d927b0abf"
}
}
],
"responses": {
"200": {
"description": "Form retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form retrieved successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"type": "string",
"example": "intake"
},
"description": {
"type": "string",
"example": "Initial patient information collection form"
},
"success_message": {
"type": "string",
"example": "Thank you! Your form has been submitted successfully"
},
"submit_button_title": {
"type": "string",
"example": "Submit Application"
},
"logo_url": {
"type": "string",
"example": "https://example.com/logo.png",
"nullable": true
},
"banner_url": {
"type": "string",
"example": "https://example.com/banner.jpg",
"nullable": true
},
"organization_display": {
"description": "Organization public details and display settings",
"properties": {
"name": {
"type": "string",
"example": "Acme Medical Clinic"
},
"display_title": {
"type": "string",
"example": "Welcome to Acme Medical"
},
"description": {
"type": "string",
"example": "Professional healthcare services"
},
"logo": {
"type": "string",
"example": "https://example.com/org-logo.png",
"nullable": true
},
"banner": {
"type": "string",
"example": "https://example.com/org-banner.jpg",
"nullable": true
},
"background_image": {
"type": "string",
"example": "https://example.com/bg.jpg",
"nullable": true
},
"secondary_cta_title": {
"type": "string",
"example": "Learn More"
},
"secondary_cta_url": {
"type": "string",
"example": "https://example.com/learn-more",
"nullable": true
},
"background_color": {
"type": "string",
"example": "#ffffff"
},
"theme": {
"type": "string",
"example": "default",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"request_info": {
"description": "Form request context when request_id is provided",
"properties": {
"id": {
"description": "Form request client UUID",
"type": "string",
"format": "uuid",
"example": "14b8fec6-3c9d-4778-a45a-242d927b0abf"
},
"client_id": {
"type": "integer",
"example": 70
},
"client_name": {
"type": "string",
"example": "ASIKHALAYE SAMUEL"
},
"is_completed": {
"type": "boolean",
"example": false
},
"is_email_sent": {
"type": "boolean",
"example": true
},
"is_sms_sent": {
"type": "boolean",
"example": false
},
"frontend_url": {
"type": "string",
"example": "https://app.dev.migranium.com/form/a45212e5-e155-44bf-8795-0f4ff5727f72?request_id=14b8fec6-3c9d-4778-a45a-242d927b0abf"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 70
},
"full_name": {
"type": "string",
"example": "ASIKHALAYE SAMUEL"
},
"email": {
"type": "string",
"example": "s.ammyb.oy.as@gmail.com"
},
"phone_number": {
"type": "string",
"example": "+2348100736345"
}
},
"type": "object"
},
"location": {
"description": "Location information when form request has location context",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Office"
},
"address": {
"type": "string",
"example": "123 Main Street"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"country": {
"type": "string",
"example": "USA"
}
},
"type": "object",
"nullable": true
},
"station": {
"description": "Station information when form request has station context",
"properties": {
"id": {
"type": "integer",
"example": 2
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception area"
}
},
"type": "object",
"nullable": true
},
"referral": {
"description": "Referral context returned when the form is of type referral and linked to an existing referral submission",
"properties": {
"status": {
"description": "Latest referral submission status",
"type": "string",
"example": "accepted"
},
"referral_uuid": {
"type": "string",
"format": "uuid",
"example": "7f0b6906-a4f4-4f31-ac93-242594b50d59"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-05T14:21:00.000Z"
},
"business": {
"description": "Partner business details when the referral is accepted",
"properties": {
"id": {
"type": "integer",
"example": 42
},
"name": {
"type": "string",
"example": "Partner Medical Clinic"
},
"display_title": {
"type": "string",
"example": "Partner Medical"
},
"email": {
"type": "string",
"example": "contact@partnerclinic.com"
},
"phone_number": {
"type": "string",
"example": "+1-555-987-6543"
},
"address": {
"type": "string",
"example": "456 Partner Street"
},
"city": {
"type": "string",
"example": "Los Angeles"
},
"state": {
"type": "string",
"example": "CA"
},
"country": {
"type": "string",
"example": "USA"
},
"logo_url": {
"type": "string",
"example": "https://example.com/logos/partner.png"
}
},
"type": "object",
"nullable": true
}
},
"type": "object",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"available_locations": {
"description": "Available locations when no request context (direct form access)",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Office"
},
"address": {
"type": "string",
"example": "123 Main Street"
}
},
"type": "object"
},
"nullable": true
},
"available_stations": {
"description": "Available stations when no request context (direct form access)",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception area"
},
"location_id": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"nullable": true
},
"sections": {
"description": "Form sections with fields and options",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "section_123e4567-e89b-12d3-a456-426614174000"
},
"title": {
"type": "string",
"example": "Personal Information"
},
"description": {
"type": "string",
"example": "Please provide your basic information"
},
"order": {
"type": "integer",
"example": 1
},
"fields": {
"description": "Fields within this section",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "field_123e4567-e89b-12d3-a456-426614174000"
},
"type": {
"type": "string",
"example": "text"
},
"title": {
"type": "string",
"example": "Full Name"
},
"placeholder": {
"type": "string",
"example": "Enter your full name"
},
"required": {
"type": "boolean",
"example": true
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Form not found or not available for public access",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Form is not live or not available for public access",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form not available for public access"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Form is not live or accessible"
]
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/client_api/intake-form/{form_path}": {
"get": {
"tags": [
"PublicForms"
],
"summary": "Get a form for public filling",
"description": "Retrieve a form by UUID for public access. No authentication or organization headers required. Only returns live forms.",
"operationId": "35e9d5b902f7b9c9cea0945cfa89dd55",
"parameters": [
{
"name": "form_path",
"in": "path",
"description": "Form UUID or link path to retrieve",
"required": true,
"schema": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
},
{
"name": "customer_id",
"in": "query",
"description": "Optional customer ID for pre-filling form data",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "request_id",
"in": "query",
"description": "Optional request identifier for tracking/deep link (e.g., form request client UUID)",
"required": false,
"schema": {
"type": "string",
"example": "14b8fec6-3c9d-4778-a45a-242d927b0abf"
}
}
],
"responses": {
"200": {
"description": "Form retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form retrieved successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"type": "string",
"example": "intake"
},
"description": {
"type": "string",
"example": "Initial patient information collection form"
},
"success_message": {
"type": "string",
"example": "Thank you! Your form has been submitted successfully"
},
"submit_button_title": {
"type": "string",
"example": "Submit Application"
},
"logo_url": {
"type": "string",
"example": "https://example.com/logo.png",
"nullable": true
},
"banner_url": {
"type": "string",
"example": "https://example.com/banner.jpg",
"nullable": true
},
"organization_display": {
"description": "Organization public details and display settings",
"properties": {
"name": {
"type": "string",
"example": "Acme Medical Clinic"
},
"display_title": {
"type": "string",
"example": "Welcome to Acme Medical"
},
"description": {
"type": "string",
"example": "Professional healthcare services"
},
"logo": {
"type": "string",
"example": "https://example.com/org-logo.png",
"nullable": true
},
"banner": {
"type": "string",
"example": "https://example.com/org-banner.jpg",
"nullable": true
},
"background_image": {
"type": "string",
"example": "https://example.com/bg.jpg",
"nullable": true
},
"secondary_cta_title": {
"type": "string",
"example": "Learn More"
},
"secondary_cta_url": {
"type": "string",
"example": "https://example.com/learn-more",
"nullable": true
},
"background_color": {
"type": "string",
"example": "#ffffff"
},
"theme": {
"type": "string",
"example": "default",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"request_info": {
"description": "Form request context when request_id is provided",
"properties": {
"id": {
"description": "Form request client UUID",
"type": "string",
"format": "uuid",
"example": "14b8fec6-3c9d-4778-a45a-242d927b0abf"
},
"client_id": {
"type": "integer",
"example": 70
},
"client_name": {
"type": "string",
"example": "ASIKHALAYE SAMUEL"
},
"is_completed": {
"type": "boolean",
"example": false
},
"is_email_sent": {
"type": "boolean",
"example": true
},
"is_sms_sent": {
"type": "boolean",
"example": false
},
"frontend_url": {
"type": "string",
"example": "https://app.dev.migranium.com/form/a45212e5-e155-44bf-8795-0f4ff5727f72?request_id=14b8fec6-3c9d-4778-a45a-242d927b0abf"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 70
},
"full_name": {
"type": "string",
"example": "ASIKHALAYE SAMUEL"
},
"email": {
"type": "string",
"example": "s.ammyb.oy.as@gmail.com"
},
"phone_number": {
"type": "string",
"example": "+2348100736345"
}
},
"type": "object"
},
"location": {
"description": "Location information when form request has location context",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Office"
},
"address": {
"type": "string",
"example": "123 Main Street"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"country": {
"type": "string",
"example": "USA"
}
},
"type": "object",
"nullable": true
},
"station": {
"description": "Station information when form request has station context",
"properties": {
"id": {
"type": "integer",
"example": 2
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception area"
}
},
"type": "object",
"nullable": true
},
"referral": {
"description": "Referral context returned when the form is of type referral and linked to an existing referral submission",
"properties": {
"status": {
"description": "Latest referral submission status",
"type": "string",
"example": "accepted"
},
"referral_uuid": {
"type": "string",
"format": "uuid",
"example": "7f0b6906-a4f4-4f31-ac93-242594b50d59"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-05T14:21:00.000Z"
},
"business": {
"description": "Partner business details when the referral is accepted",
"properties": {
"id": {
"type": "integer",
"example": 42
},
"name": {
"type": "string",
"example": "Partner Medical Clinic"
},
"display_title": {
"type": "string",
"example": "Partner Medical"
},
"email": {
"type": "string",
"example": "contact@partnerclinic.com"
},
"phone_number": {
"type": "string",
"example": "+1-555-987-6543"
},
"address": {
"type": "string",
"example": "456 Partner Street"
},
"city": {
"type": "string",
"example": "Los Angeles"
},
"state": {
"type": "string",
"example": "CA"
},
"country": {
"type": "string",
"example": "USA"
},
"logo_url": {
"type": "string",
"example": "https://example.com/logos/partner.png"
}
},
"type": "object",
"nullable": true
}
},
"type": "object",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"available_locations": {
"description": "Available locations when no request context (direct form access)",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Office"
},
"address": {
"type": "string",
"example": "123 Main Street"
}
},
"type": "object"
},
"nullable": true
},
"available_stations": {
"description": "Available stations when no request context (direct form access)",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Reception Desk"
},
"description": {
"type": "string",
"example": "Main reception area"
},
"location_id": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"nullable": true
},
"sections": {
"description": "Form sections with fields and options",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "section_123e4567-e89b-12d3-a456-426614174000"
},
"title": {
"type": "string",
"example": "Personal Information"
},
"description": {
"type": "string",
"example": "Please provide your basic information"
},
"order": {
"type": "integer",
"example": 1
},
"fields": {
"description": "Fields within this section",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "field_123e4567-e89b-12d3-a456-426614174000"
},
"type": {
"type": "string",
"example": "text"
},
"title": {
"type": "string",
"example": "Full Name"
},
"placeholder": {
"type": "string",
"example": "Enter your full name"
},
"required": {
"type": "boolean",
"example": true
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Form not found or not available for public access",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Form is not live or not available for public access",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form not available for public access"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Form is not live or accessible"
]
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/public/forms/{form_path}/responses": {
"post": {
"tags": [
"PublicForms"
],
"summary": "Submit a response to a public form",
"description": "Submit form response data for a public form. No authentication required. Optionally include customer_id or request_id.",
"operationId": "e8dbc9e0d70b4b5ce86efc3c23c32b5b",
"parameters": [
{
"name": "form_path",
"in": "path",
"description": "Form UUID or link path to submit response to",
"required": true,
"schema": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"requestBody": {
"description": "Form response data with field responses and optional client information",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"responses"
],
"properties": {
"client_id": {
"description": "Optional client ID to associate with this response",
"type": "integer",
"example": 123,
"nullable": true
},
"session_id": {
"description": "Optional session identifier for tracking",
"type": "string",
"example": "sess_abc123",
"nullable": true
},
"request_id": {
"description": "Optional request ID (UUID) to link this response to a form request client",
"type": "string",
"format": "uuid",
"example": "14b8fec6-3c9d-4778-a45a-242d927b0abf",
"nullable": true
},
"location_id": {
"description": "Optional location ID for direct form submissions (when no request_id provided)",
"type": "integer",
"example": 1,
"nullable": true
},
"station_id": {
"description": "Optional station ID for direct form submissions (when no request_id provided)",
"type": "integer",
"example": 2,
"nullable": true
},
"responses": {
"description": "Array of field responses",
"type": "array",
"items": {
"properties": {
"field_id": {
"description": "Field UUID",
"type": "string",
"format": "uuid",
"example": "f1e2d3c4-5678-90ab-cdef-1234567890ab"
},
"value": {
"description": "Field response value",
"oneOf": [
{
"type": "string",
"example": "John Doe"
},
{
"type": "number",
"example": 25
},
{
"type": "boolean",
"example": true
},
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"option1",
"option2"
]
}
]
},
"value_type": {
"description": "Type of the value (text, number, email, etc.)",
"type": "string",
"example": "text"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Form response submitted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "form response created successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"form_id": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"customer_id": {
"type": "integer",
"example": 123,
"nullable": true
},
"session_id": {
"type": "string",
"example": "sess_abc123",
"nullable": true
},
"form_request_client_id": {
"type": "integer",
"example": 456,
"nullable": true
},
"location_id": {
"description": "Location ID if provided or inherited from form request",
"type": "integer",
"example": 1,
"nullable": true
},
"station_id": {
"description": "Station ID if provided or inherited from form request",
"type": "integer",
"example": 2,
"nullable": true
},
"status": {
"description": "Status will be 'completed' for public submissions",
"type": "string",
"example": "completed"
},
"submitted_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error in form response data",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"responses": [
"The responses field is required."
]
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Form not found or not available for public submissions",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form not found"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v1/queue/list": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get all queue orders",
"description": "Retrieve all queue orders for the current user's location with total count and wait time",
"operationId": "getQueueList",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"responses": {
"200": {
"description": "Queue orders retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"total_count": {
"description": "Total number of bookings in queue",
"type": "integer",
"example": 15
},
"total_wait_time": {
"description": "Formatted total wait time",
"type": "string",
"example": "7 hours 30 minutes"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QueueBookingResource"
}
},
"message": {
"type": "string",
"example": "User queue orders fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/bookings/{bookingUuid}": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get booking details",
"description": "Retrieve comprehensive details for a specific booking",
"operationId": "getBookingDetail",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "bookingUuid",
"in": "path",
"description": "Booking UUID",
"required": true,
"schema": {
"type": "string",
"example": "bk_abc123"
}
}
],
"responses": {
"200": {
"description": "Booking details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking details retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/BookingDetailResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Booking not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Queue Management"
],
"summary": "Delete a booking",
"description": "Cancel a booking and remove it from the queue",
"operationId": "deleteBooking",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "bookingUuid",
"in": "path",
"description": "Booking UUID",
"required": true,
"schema": {
"type": "string",
"example": "bk_abc123"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"cancellation_message": {
"description": "Optional cancellation message",
"type": "string",
"example": "Patient requested cancellation"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Booking cancelled successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking updated successfully"
},
"data": {
"oneOf": [
{
"$ref": "#/components/schemas/QueueBookingResource"
}
],
"nullable": true
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Booking not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Queue Management"
],
"summary": "Update a booking",
"description": "Update a booking's status, position, provider, priority, or follow-up flag",
"operationId": "updateBooking",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "bookingUuid",
"in": "path",
"description": "Booking UUID",
"required": true,
"schema": {
"type": "string",
"example": "bk_abc123"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"description": "New booking status",
"type": "string",
"enum": [
"pending",
"confirmed",
"checked_in",
"in_progress",
"serving",
"checked-in",
"completed",
"cancelled",
"no_show"
],
"example": "checked-in"
},
"location_station_id": {
"description": "New location station ID",
"type": "integer",
"example": 5
},
"position": {
"description": "New queue position",
"type": "integer",
"minimum": 1,
"example": 2
},
"priority": {
"description": "Priority level",
"type": "string",
"example": "high"
},
"is_follow_up": {
"description": "Follow-up booking flag",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Booking updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking updated successfully"
},
"data": {
"$ref": "#/components/schemas/QueueBookingResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Booking not found"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/bookings/bulk-update": {
"post": {
"tags": [
"Queue Management"
],
"summary": "Bulk update bookings",
"description": "Update multiple bookings at once with the same changes",
"operationId": "bulkUpdateBookings",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"booking_ids"
],
"properties": {
"booking_ids": {
"description": "Array of booking IDs to update",
"type": "array",
"items": {
"type": "string"
},
"example": [
"bk_abc123",
"bk_def456",
"bk_ghi789"
]
},
"status": {
"description": "New status for all bookings",
"type": "string",
"enum": [
"pending",
"confirmed",
"checked_in",
"in_progress",
"serving",
"checked-in",
"completed",
"cancelled",
"no_show"
],
"example": "checked-in"
},
"location_station_id": {
"description": "New location station ID",
"type": "integer",
"example": 5
},
"position": {
"description": "New queue position",
"type": "integer",
"minimum": 1,
"example": 2
},
"priority": {
"description": "Priority level",
"type": "string",
"example": "high"
},
"is_follow_up": {
"description": "Follow-up booking flag",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Bulk update completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Bulk update completed"
},
"data": {
"properties": {
"total_processed": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Some bookings not found"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/bookings/bulk-delete": {
"delete": {
"tags": [
"Queue Management"
],
"summary": "Bulk delete bookings",
"description": "Cancel multiple bookings at once",
"operationId": "bulkDeleteBookings",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"booking_ids"
],
"properties": {
"booking_ids": {
"description": "Array of booking IDs to cancel",
"type": "array",
"items": {
"type": "string"
},
"example": [
"bk_abc123",
"bk_def456"
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Bulk delete completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Bulk delete completed"
},
"data": {
"properties": {
"total_processed": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Some bookings not found"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/clear": {
"delete": {
"tags": [
"Queue Management"
],
"summary": "Clear queue",
"description": "Remove all bookings from the queue",
"operationId": "clearQueue",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"responses": {
"200": {
"description": "Queue cleared successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Queue cleared successfully"
},
"data": {
"properties": {
"removed_count": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/bookings": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get today's bookings",
"description": "Retrieve a paginated list of today's bookings with optional filters for status, clients, locations, services, stations, providers, booking source, and dates",
"operationId": "getBookings",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1,
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"schema": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"example": 20
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"schema": {
"type": "string",
"enum": [
"client",
"location",
"provider",
"service",
"booking_date",
"booking_type",
"created_at",
"status"
],
"example": "created_at"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"schema": {
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
{
"name": "search",
"in": "query",
"description": "Search query string",
"schema": {
"type": "string",
"maxLength": 255,
"example": "John"
}
},
{
"name": "status[]",
"in": "query",
"description": "Filter by booking status(es)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"pending",
"confirmed",
"checked_in",
"in_progress",
"completed",
"cancelled",
"no_show",
"rescheduled",
"rejected",
"awaiting_confirmation",
"reschedule_requested",
"cancellation_requested",
"on_hold",
"late",
"partially_completed",
"follow_up_required"
]
}
}
},
{
"name": "booking_type",
"in": "query",
"description": "Filter by booking type",
"schema": {
"type": "string",
"example": "walk_in"
}
},
{
"name": "clients[]",
"in": "query",
"description": "Filter by client IDs (array)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
{
"name": "locations[]",
"in": "query",
"description": "Filter by location IDs (array)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
{
"name": "services[]",
"in": "query",
"description": "Filter by service IDs (array)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
{
"name": "stations[]",
"in": "query",
"description": "Filter by Location station IDs (array - location_station table)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
{
"name": "providers[]",
"in": "query",
"description": "Filter by Provider IDs (array - stations table)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
},
{
"name": "through[]",
"in": "query",
"description": "Filter by booking source (array)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"admin",
"link",
"web",
"qr"
]
}
}
},
{
"name": "date",
"in": "query",
"description": "Filter by date created (YYYY-MM-DD format). Must not be in the future.",
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-30"
}
},
{
"name": "booking_date",
"in": "query",
"description": "Filter by booking date (YYYY-MM-DD format). Must not be in the future.",
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-30"
}
},
{
"name": "location",
"in": "query",
"description": "Filter by a single location ID",
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "station",
"in": "query",
"description": "Filter by a single Location station ID (location_station table)",
"schema": {
"type": "integer",
"example": 7
}
},
{
"name": "provider",
"in": "query",
"description": "Filter by a single Provider ID (stations table)",
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "client",
"in": "query",
"description": "Filter by a single client ID",
"schema": {
"type": "integer",
"example": 123
}
},
{
"name": "service",
"in": "query",
"description": "Filter by a single service ID",
"schema": {
"type": "integer",
"example": 5
}
}
],
"responses": {
"200": {
"description": "Successful response with paginated bookings",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Bookings fetched successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BookingResource"
}
},
"meta": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"from": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 5
},
"per_page": {
"type": "integer",
"example": 20
},
"to": {
"type": "integer",
"example": 20
},
"total": {
"type": "integer",
"example": 100
}
},
"type": "object"
},
"links": {
"properties": {
"first": {
"type": "string",
"example": "http://api.example.com/bookings?page=1"
},
"last": {
"type": "string",
"example": "http://api.example.com/bookings?page=5"
},
"prev": {
"type": "string",
"example": null,
"nullable": true
},
"next": {
"type": "string",
"example": "http://api.example.com/bookings?page=2"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Queue Management"
],
"summary": "Add booking to queue",
"description": "Create a new booking and add it to the queue",
"operationId": "addBooking",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"client_id",
"location_station_id",
"service_id"
],
"properties": {
"client_id": {
"description": "Client ID",
"type": "integer",
"example": 123
},
"location_station_id": {
"description": "Location station ID",
"type": "integer",
"example": 10
},
"service_id": {
"description": "Service ID",
"type": "integer",
"example": 5
},
"status": {
"description": "Initial booking status",
"type": "string",
"enum": [
"pending",
"confirmed",
"checked_in"
],
"example": "checked_in"
},
"position": {
"description": "Queue position",
"type": "integer",
"minimum": 1,
"example": 1
},
"priority": {
"description": "Priority level",
"type": "string",
"example": "normal"
},
"is_follow_up": {
"description": "Follow-up booking flag",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Booking added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking added to queue successfully"
},
"data": {
"$ref": "#/components/schemas/QueueBookingResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/bookings/{bookingUuid}/notify": {
"post": {
"tags": [
"Queue Management"
],
"summary": "Notify booking client",
"description": "Send a notification to the client associated with the booking",
"operationId": "notifyBooking",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "bookingUuid",
"in": "path",
"description": "Booking UUID",
"required": true,
"schema": {
"type": "string",
"example": "bk_abc123"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"description": "Optional custom notification message",
"type": "string",
"example": "Your appointment is ready"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Notification sent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Notification sent successfully"
},
"data": {
"type": "array",
"items": {}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Booking not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/bookings/notify-bulk": {
"post": {
"tags": [
"Queue Management"
],
"summary": "Notify multiple booking clients",
"description": "Send notifications to clients of multiple bookings at once",
"operationId": "notifyBulkBookings",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"booking_ids"
],
"properties": {
"booking_ids": {
"description": "Array of booking IDs to notify",
"type": "array",
"items": {
"type": "string"
},
"example": [
"bk_abc123",
"bk_def456"
]
},
"message": {
"description": "Optional custom notification message",
"type": "string",
"example": "Your appointments are ready"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Notifications sent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Notification sent successfully"
},
"data": {
"type": "array",
"items": {}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/today": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get today's bookings",
"description": "Retrieve all bookings for today with queue information",
"operationId": "getTodaysBookings",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"responses": {
"200": {
"description": "Today's bookings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"total_count": {
"description": "Total number of today's bookings",
"type": "integer",
"example": 20
},
"total_wait_time": {
"description": "Formatted total wait time",
"type": "string",
"example": "10 hours"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QueueBookingResource"
}
},
"message": {
"type": "string",
"example": "User queue orders fetched successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/preference": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get current user queue preferences",
"description": "Retrieve the personalized queue filtering and display preferences for the authenticated user",
"operationId": "getUserQueuePreference",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"responses": {
"200": {
"description": "User preferences retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Preference returned"
},
"data": {
"$ref": "#/components/schemas/UserQueuePreferenceResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Queue Management"
],
"summary": "Update user queue preferences",
"description": "Update the personalized queue filtering and display preferences for the authenticated user",
"operationId": "updateUserQueuePreference",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserQueuePreferenceUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "User preferences updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "preference updated successfully"
},
"data": {
"$ref": "#/components/schemas/UserQueuePreferenceResource"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/preference/locations": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get available locations",
"description": "Retrieve a paginated list of locations available for the authenticated user to filter the queue",
"operationId": "getQueueLocations",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "search",
"in": "query",
"description": "Search by location name",
"schema": {
"type": "string",
"example": "Main"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Locations retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "locations fetched successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationWithProvidersResource"
}
},
"meta": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 5
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/preference/{locationId}/providers": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get location providers",
"description": "Retrieve a paginated list of providers/stations available at a specific location",
"operationId": "getLocationProviders",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "locationId",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search by provider/station name",
"schema": {
"type": "string",
"example": "Dr."
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter providers by service ID",
"schema": {
"type": "integer",
"example": 5
}
}
],
"responses": {
"200": {
"description": "Providers retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "providers fetched successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BookingProviderResource"
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Location not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/preference/{locationId}/services": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get location services",
"description": "Retrieve a paginated list of services available at a specific location or for specific providers",
"operationId": "getLocationServices",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "locationId",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search by service name",
"schema": {
"type": "string",
"example": "Consult"
}
},
{
"name": "provider_id",
"in": "query",
"description": "Filter services by a single provider ID",
"schema": {
"type": "integer",
"example": 10
}
},
{
"name": "providers",
"in": "query",
"description": "Filter services by multiple provider IDs (comma-separated or array)",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
}
],
"responses": {
"200": {
"description": "Services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "services fetched successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SimpleServiceResource"
}
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"description": "Location not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/queue/preference/clients": {
"get": {
"tags": [
"Queue Management"
],
"summary": "Get clients",
"description": "Retrieve a paginated list of clients available for the current organization",
"operationId": "getQueueClients",
"parameters": [
{
"$ref": "#/components/parameters/OrganizationIdHeader"
},
{
"name": "search",
"in": "query",
"description": "Search by client name, email, or phone",
"schema": {
"type": "string",
"example": "John"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Clients retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "clients fetched successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SimpleClientResource"
}
},
"meta": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 10
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 150
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/partners/all": {
"get": {
"tags": [
"Referral Partners"
],
"summary": "Get all referral partners",
"description": "Retrieve all referral partners for the business without pagination.",
"operationId": "getAllReferralPartners",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by single partner type ID",
"schema": {
"type": "integer"
}
},
{
"name": "types",
"in": "query",
"description": "Filter by multiple partner type IDs (comma-separated)",
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "referral_type",
"in": "query",
"description": "Filter by single referral type",
"schema": {
"type": "string",
"enum": [
"inbound",
"outbound",
"both"
]
}
},
{
"name": "referral_types",
"in": "query",
"description": "Filter by multiple referral types (comma-separated)",
"schema": {
"type": "string",
"example": "inbound,outbound"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by service ID",
"schema": {
"type": "integer"
}
},
{
"name": "search",
"in": "query",
"description": "Search term for partner name",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization partner list"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Partner Business"
},
"type": {
"type": "object"
},
"referral_type": {
"type": "string",
"example": "both"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/partners": {
"get": {
"tags": [
"Referral Partners"
],
"summary": "Get paginated referral partners",
"description": "Retrieve paginated list of referral partners with filtering, search, and sorting capabilities.",
"operationId": "getReferralPartners",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"schema": {
"type": "integer",
"default": 15
}
},
{
"name": "search",
"in": "query",
"description": "Search term for partner name",
"schema": {
"type": "string"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"schema": {
"type": "string",
"enum": [
"name",
"referral_type",
"created_at"
]
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"schema": {
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc"
]
}
},
{
"name": "type",
"in": "query",
"description": "Filter by single partner type ID",
"schema": {
"type": "integer"
}
},
{
"name": "types",
"in": "query",
"description": "Filter by multiple partner type IDs (comma-separated)",
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "referral_type",
"in": "query",
"description": "Filter by single referral type",
"schema": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"both"
]
}
},
{
"name": "referral_types",
"in": "query",
"description": "Filter by multiple referral types (comma-separated)",
"schema": {
"type": "string",
"example": "incoming,outgoing"
}
},
{
"name": "service_id",
"in": "query",
"description": "Filter by service ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral Partners"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Partner Business"
},
"email": {
"type": "string",
"example": "partner@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"country": {
"type": "string",
"example": "USA"
},
"partnership_status": {
"type": "string",
"example": "active"
},
"partner_type_id": {
"type": "integer",
"example": 1
},
"referral_type": {
"type": "string",
"example": "both"
},
"locations_count": {
"type": "integer",
"example": 2
},
"stations_count": {
"type": "integer",
"example": 5
},
"services_count": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"meta": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 5
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 75
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Referral Partners"
],
"summary": "Create a new referral partner",
"description": "Create a new referral partner with associated services and providers.",
"operationId": "createReferralPartner",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"email",
"first_name",
"last_name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Partner Business Name"
},
"email": {
"type": "string",
"format": "email",
"maxLength": 255,
"example": "partner@example.com"
},
"phone": {
"type": "string",
"maxLength": 50,
"example": "+1234567890"
},
"address": {
"type": "string",
"maxLength": 255,
"example": "123 Main Street"
},
"country": {
"type": "string",
"maxLength": 100,
"example": "USA"
},
"state": {
"type": "string",
"maxLength": 100,
"example": "NY"
},
"city": {
"type": "string",
"maxLength": 100,
"example": "New York"
},
"business_category_id": {
"type": "integer",
"example": 1
},
"first_name": {
"type": "string",
"maxLength": 255,
"example": "John"
},
"last_name": {
"type": "string",
"maxLength": 255,
"example": "Doe"
},
"referral_type": {
"type": "string",
"enum": [
"inbound",
"outbound",
"both"
],
"example": "both"
},
"partner_type_id": {
"type": "integer",
"example": 1
},
"service_ids": {
"description": "Array of existing service IDs to associate",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"new_services": {
"description": "Array of new services to create",
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Consultation"
},
"description": {
"type": "string",
"maxLength": 5000,
"example": "Initial consultation service"
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
},
"time_in_minute": {
"type": "integer",
"example": 30
},
"appointment_methods": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
},
"providers": {
"description": "Array of providers for this partner",
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Dr. Smith"
},
"email": {
"type": "string",
"format": "email",
"example": "dr.smith@example.com"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Referral partner created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral Service"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Partner Business"
},
"email": {
"type": "string",
"example": "partner@example.com"
},
"referral_type": {
"type": "string",
"example": "both"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/partners/{partnerId}": {
"get": {
"tags": [
"Referral Partners"
],
"summary": "Get a specific referral partner",
"description": "Retrieve detailed information about a specific referral partner.",
"operationId": "getReferralPartner",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "partnerId",
"in": "path",
"description": "Partner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral Partner"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Partner Business"
},
"email": {
"type": "string",
"example": "partner@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"country": {
"type": "string",
"example": "USA"
},
"partnership_status": {
"type": "string",
"example": "active"
},
"partner_type_id": {
"type": "integer",
"example": 1
},
"referral_type": {
"type": "string",
"example": "both"
},
"locations_count": {
"type": "integer",
"example": 2
},
"stations_count": {
"type": "integer",
"example": 5
},
"services_count": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Partner not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Referral Partners"
],
"summary": "Update a referral partner",
"description": "Update an existing referral partner's information.",
"operationId": "updateReferralPartner",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "partnerId",
"in": "path",
"description": "Partner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Updated Partner Name"
},
"email": {
"type": "string",
"format": "email",
"maxLength": 255,
"example": "updated@example.com"
},
"phone": {
"type": "string",
"maxLength": 50,
"example": "+1234567890"
},
"address": {
"type": "string",
"maxLength": 255,
"example": "456 New Street"
},
"country": {
"type": "string",
"maxLength": 100,
"example": "USA"
},
"state": {
"type": "string",
"maxLength": 100,
"example": "CA"
},
"city": {
"type": "string",
"maxLength": 100,
"example": "Los Angeles"
},
"referral_type": {
"type": "string",
"enum": [
"inbound",
"outbound",
"both"
],
"example": "inbound"
},
"partner_type_id": {
"type": "integer",
"example": 1
},
"first_name": {
"type": "string",
"maxLength": 255,
"example": "John"
},
"last_name": {
"type": "string",
"maxLength": 255,
"example": "Doe"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral partner updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral Partner updated"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Updated Partner Name"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Partner not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Referral Partners"
],
"summary": "Delete a referral partner",
"description": "Delete an existing referral partner relationship.",
"operationId": "deleteReferralPartner",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "partnerId",
"in": "path",
"description": "Partner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Referral partner deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral Partner deleted successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Partner not found"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/partners/{partnerId}/status": {
"patch": {
"tags": [
"Referral Partners"
],
"summary": "Update partner status",
"description": "Update the partnership status (active or inactive)",
"operationId": "updateReferralPartnerStatus",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Business/Organization ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "partnerId",
"in": "path",
"description": "Partner ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"pending"
],
"example": "active"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Status updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Partner status updated successfully"
},
"data": {
"properties": {
"status": {
"type": "string",
"example": "active"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Partner not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/services": {
"get": {
"tags": [
"Referral Services"
],
"summary": "List referral services",
"description": "Retrieve a paginated list of referral services for the organization.",
"operationId": "15195bba3a7709dcbf5cc6fea574c040",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search by service name",
"required": false,
"schema": {
"type": "string",
"example": "consultation"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by referral type (single or comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "incoming"
}
},
{
"name": "page",
"in": "query",
"description": "Page number",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Items per page",
"required": false,
"schema": {
"type": "integer",
"example": 15
}
}
],
"responses": {
"200": {
"description": "Referral services retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral service retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReferralServiceResource"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 45
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Referral Services"
],
"summary": "Create referral service",
"description": "Create a new referral service for the organization.",
"operationId": "446da3e637b608591b919f118ded6c6a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReferralServiceUpsertRequest"
}
}
}
},
"responses": {
"201": {
"description": "Referral service created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral service created successfully"
},
"data": {
"$ref": "#/components/schemas/ReferralServiceResource"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/services/{serviceId}": {
"get": {
"tags": [
"Referral Services"
],
"summary": "Get referral service",
"description": "Retrieve a single referral service by ID.",
"operationId": "c17fb5fd5e4d9d9db4d5f49d958360cb",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "serviceId",
"in": "path",
"description": "Referral service ID",
"required": true,
"schema": {
"type": "integer",
"example": 10
}
}
],
"responses": {
"200": {
"description": "Referral service retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral service retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/ReferralServiceResource"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Referral service not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Referral Services"
],
"summary": "Update referral service",
"description": "Update an existing referral service.",
"operationId": "0f250619938645576a074f368013b4f1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "serviceId",
"in": "path",
"description": "Referral service ID",
"required": true,
"schema": {
"type": "integer",
"example": 10
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReferralServiceUpsertRequest"
}
}
}
},
"responses": {
"200": {
"description": "Referral service updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral service updated successfully"
},
"data": {
"$ref": "#/components/schemas/ReferralServiceResource"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Referral service not found"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Referral Services"
],
"summary": "Delete referral service",
"description": "Delete an existing referral service.",
"operationId": "a39dedd331ca1397d77b6eef09ff0da3",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "serviceId",
"in": "path",
"description": "Referral service ID",
"required": true,
"schema": {
"type": "integer",
"example": 10
}
}
],
"responses": {
"200": {
"description": "Referral service deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral service deleted successfully"
},
"data": {
"type": "null",
"example": null
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Referral service not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/settings": {
"get": {
"tags": [
"Referral Settings"
],
"summary": "Get general referral settings",
"description": "Retrieve general referral settings including type of referral and partner configurations",
"operationId": "getGeneralReferralSettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral General Settings"
},
"data": {
"properties": {
"type_of_refferal": {
"type": "string",
"enum": [
"both",
"incoming",
"outgoing"
],
"example": "both"
},
"partners": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "Partner Clinic"
},
"referral_type": {
"type": "string",
"enum": [
"both",
"incoming",
"outgoing"
],
"example": "both"
},
"is_edit_allowed": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Referral Settings"
],
"summary": "Update general referral settings",
"description": "Update general referral settings including type of referral and partner configurations",
"operationId": "updateGeneralReferralSettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"type_of_referral": {
"type": "string",
"enum": [
"both",
"incoming",
"outgoing"
],
"example": "both"
},
"partners": {
"type": "array",
"items": {
"properties": {
"id": {
"description": "Partner business ID",
"type": "integer",
"example": 123
},
"referral_type": {
"type": "string",
"enum": [
"both",
"incoming",
"outgoing"
],
"example": "both"
},
"is_edit_allowed": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Settings updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral General Settings updated successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/settings/incoming": {
"get": {
"tags": [
"Referral Settings"
],
"summary": "Get incoming referral settings",
"description": "Retrieve settings for incoming referrals including auto-approve, limit rules, and nudge rules",
"operationId": "getIncomingReferralSettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Incoming referral setting"
},
"data": {
"properties": {
"auto_approve": {
"type": "boolean",
"example": false
},
"limit_rules": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"example": 10
}
},
"type": "object"
},
"nudge_rules": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"example": 10
}
},
"type": "object"
},
"store_after_approval": {
"type": "string",
"example": "store_incoming_after_approval"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Referral Settings"
],
"summary": "Update incoming referral settings",
"description": "Update settings for incoming referrals including auto-approve, limit rules, and nudge rules",
"operationId": "updateIncomingReferralSettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"auto_approve": {
"type": "boolean",
"example": false
},
"limits": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"minimum": 1,
"example": 10
}
},
"type": "object"
},
"nudge_rules": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"minimum": 1,
"example": 10
}
},
"type": "object"
},
"store_after_approval": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Settings updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Incoming referral setting updated successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/referral/settings/outgoing": {
"get": {
"tags": [
"Referral Settings"
],
"summary": "Get outgoing referral settings",
"description": "Retrieve settings for outgoing referrals including auto-approve, limit rules, and nudge rules",
"operationId": "getOutgoingReferralSettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Settings retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Outgoing referral setting"
},
"data": {
"properties": {
"auto_approve": {
"type": "boolean",
"example": false
},
"limit_rules": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"example": 10
}
},
"type": "object"
},
"nudge_rules": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"example": 10
}
},
"type": "object"
},
"store_after_approval": {
"type": "string",
"example": "store_outgoing_after_approval"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Referral Settings"
],
"summary": "Update outgoing referral settings",
"description": "Update settings for outgoing referrals including auto-approve, limit rules, and nudge rules",
"operationId": "updateOutgoingReferralSettings",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"auto_approve": {
"type": "boolean",
"example": false
},
"limits": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"minimum": 1,
"example": 10
}
},
"type": "object"
},
"nudge_rules": {
"properties": {
"is_enabled": {
"type": "boolean",
"example": true
},
"unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days",
"months",
"years"
],
"example": "days"
},
"value": {
"type": "integer",
"minimum": 1,
"example": 10
}
},
"type": "object"
},
"store_after_approval": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Settings updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Outgoing referral setting updated successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/analytics/status": {
"get": {
"tags": [
"Referrals",
"Analytics"
],
"summary": "Get referral status analytics grouped by partner business",
"description": "Returns aggregated referral counts by partner business and status within the specified filters",
"operationId": "7e417ee2e89246ebfcb9e2a8c1640418",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter referrals created on/after this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter referrals created on/before this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "partner_business_ids[]",
"in": "query",
"description": "Filter by one or more partner business IDs",
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
}
],
"responses": {
"200": {
"description": "Analytics retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Analytics retrieved successfully"
},
"data": {
"type": "object"
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error or missing business header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business header is required"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/analytics/status/summary": {
"get": {
"tags": [
"Referrals",
"Analytics"
],
"summary": "Get aggregate referral counts by status",
"description": "Returns total referral counts grouped by status buckets",
"operationId": "83ea0b18ebbd2f881da37f71dec9448e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter referrals created on/after this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter referrals created on/before this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "Analytics retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Analytics retrieved successfully"
},
"data": {
"type": "object"
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/analytics/accepted/weekdays": {
"get": {
"tags": [
"Referrals",
"Analytics"
],
"summary": "Get accepted referral counts grouped by weekday",
"description": "Returns total accepted referrals split across weekdays",
"operationId": "e5810bc5030b6c86e005f40b0cc5bf82",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter referrals processed on/after this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter referrals processed on/before this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "Analytics retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Analytics retrieved successfully"
},
"data": {
"type": "object"
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/send": {
"post": {
"tags": [
"Referrals"
],
"summary": "Send a referral form response to partner businesses",
"description": "Send a completed referral form response to one or more partner businesses. The form must be of type 'referral' and the specified businesses must be confirmed partners.",
"operationId": "afec70f839191a3b94f1dc16f648e123",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID) of the source business",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Referral submission data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_response_uuid",
"partner_business_ids"
],
"properties": {
"form_response_uuid": {
"description": "UUID of the form response to send as referral",
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"partner_business_ids": {
"description": "Array of partner business IDs to send the referral to",
"type": "array",
"items": {
"type": "integer"
},
"example": [
5,
7,
12
]
},
"notes": {
"description": "Optional notes about the referral",
"type": "string",
"maxLength": 1000,
"example": "Urgent case requiring immediate attention"
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Referral sent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral sent to 2 partner business(es) successfully"
},
"data": {
"properties": {
"referrals": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "sent"
},
"partner_business_id": {
"type": "integer",
"example": 5
},
"sent_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Invalid request - Form not a referral type or no valid partnerships",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form must be of type 'referral' to send as referral"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Form response not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form response not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/form-responses": {
"get": {
"tags": [
"Referrals"
],
"summary": "Get referral form responses with send list",
"description": "Retrieve form responses of type 'referral' with information about which partners they were sent to",
"operationId": "340af8cf675c2ff3fb9ba585813a305a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "status",
"in": "query",
"description": "Filter by referral submission status",
"schema": {
"type": "string",
"enum": [
"pending",
"sent",
"received",
"accepted",
"rejected",
"auto_declined",
"completed"
]
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by submission date from",
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by submission date to",
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "partner_business_id",
"in": "query",
"description": "Filter by partner business ID",
"schema": {
"type": "integer",
"example": 5
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral form responses retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "form-response-uuid-123"
},
"status": {
"type": "string",
"example": "submitted"
},
"client_name": {
"type": "string",
"example": "John Doe"
},
"client_email": {
"type": "string",
"example": "john@example.com"
},
"client_phone_number": {
"type": "string",
"example": "+1234567890"
},
"submitted_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
},
"form": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Patient Referral Form"
}
},
"type": "object"
},
"partner_match_stats": {
"description": "Per-partner match statistics based on partner_mappings for this referral form response",
"type": "array",
"items": {
"properties": {
"partner_id": {
"type": "string",
"example": "21"
},
"match_percentage": {
"type": "number",
"format": "float",
"example": 66.67
}
},
"type": "object"
}
},
"send_list": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"partner_business_id": {
"type": "integer",
"example": 5
},
"partner_business_name": {
"type": "string",
"example": "Partner Clinic"
},
"status": {
"type": "string",
"example": "sent"
},
"sent_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
},
"notes": {
"type": "string",
"example": "Urgent case"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals": {
"get": {
"tags": [
"Referrals"
],
"summary": "Get unified incoming and outgoing referrals",
"description": "Returns a single paginated list that merges sent and received referrals into one resource structure",
"operationId": "00e3cb77dc10642f160dadc10a2cd5bd",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "partner_id",
"in": "query",
"description": "Counterparty business ID",
"schema": {
"type": "integer"
}
},
{
"name": "statuses[]",
"in": "query",
"description": "Filter by mapped status values",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "type",
"in": "query",
"description": "Filter by referral type",
"schema": {
"type": "string",
"enum": [
"incoming",
"outgoing"
]
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by submitted date from",
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by submitted date to",
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "search",
"in": "query",
"description": "Search by patient name, patient email, or referral ID",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of referrals per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Unified referrals retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Unified referrals retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "a4a95a44-4cc3-48e1-a4de-2f8bd03e4f1a"
},
"patient_name": {
"type": "string",
"example": "John Doe"
},
"patient_email": {
"type": "string",
"example": "john@example.com"
},
"status": {
"type": "string",
"example": "accepted"
},
"type": {
"type": "string",
"example": "incoming"
},
"submitted_at": {
"type": "string",
"format": "date-time",
"example": "2026-03-04T10:30:00Z"
}
},
"type": "object"
}
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business header is required"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Failed to retrieve unified referrals",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to retrieve unified referrals"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/sent": {
"get": {
"tags": [
"Referrals"
],
"summary": "Get referrals sent by the business",
"description": "Retrieve all referrals sent by the authenticated business to partner businesses",
"operationId": "1ffea8f4f3a22b969ff14405b56dcc71",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "status",
"in": "query",
"description": "Filter by referral status",
"schema": {
"type": "string",
"enum": [
"pending",
"sent",
"received",
"accepted",
"rejected",
"auto_declined",
"completed"
]
}
},
{
"name": "partner_business_id",
"in": "query",
"description": "Filter by partner business ID",
"schema": {
"type": "integer"
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by sent date from",
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by sent date to",
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of referrals per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Sent referrals retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "form-response-uuid-123"
},
"status": {
"type": "string",
"example": "submitted"
},
"client_name": {
"type": "string",
"example": "John Doe"
},
"client_email": {
"type": "string",
"example": "john@example.com"
},
"client_phone_number": {
"type": "string",
"example": "+1234567890"
},
"submitted_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
},
"form": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Patient Referral Form"
}
},
"type": "object"
},
"send_list": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"partner_business_id": {
"type": "integer",
"example": 5
},
"partner_business_name": {
"type": "string",
"example": "Partner Clinic"
},
"status": {
"type": "string",
"example": "sent"
},
"sent_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
},
"notes": {
"type": "string",
"example": "Urgent case"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/received": {
"get": {
"tags": [
"Referrals"
],
"summary": "Get referrals received by the business",
"description": "Retrieve all referrals received by the authenticated business from partner businesses",
"operationId": "4f3fdea288beada1c8615746489cee54",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "status",
"in": "query",
"description": "Filter by referral status",
"schema": {
"type": "string",
"enum": [
"pending",
"sent",
"received",
"accepted",
"rejected",
"auto_declined",
"completed"
]
}
},
{
"name": "source_business_id",
"in": "query",
"description": "Filter by source business ID",
"schema": {
"type": "integer"
}
},
{
"name": "partner_business_id",
"in": "query",
"description": "Alias: filter by source business ID (for UI consistency)",
"schema": {
"type": "integer"
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by sent date from",
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by sent date to",
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of referrals per page (1-100)",
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Results page number",
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Received referrals retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "sent"
},
"source_business": {
"properties": {
"id": {
"type": "integer",
"example": 3
},
"name": {
"type": "string",
"example": "Source Clinic"
}
},
"type": "object"
},
"form_response": {
"properties": {
"uuid": {
"type": "string",
"example": "form-uuid-123"
},
"client_name": {
"type": "string",
"example": "John Doe"
}
},
"type": "object"
},
"sent_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
},
"notes": {
"type": "string",
"example": "Urgent case"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}": {
"get": {
"tags": [
"Referrals"
],
"summary": "Show referral submission detail",
"description": "Retrieve a referral submission with the full form response, patient information, partner assignments, and notes.",
"operationId": "d5d6662df98e8f54cc8f924c562914d3",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID) for the authenticated business",
"required": true,
"schema": {
"type": "integer",
"example": 42
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral submission",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"responses": {
"200": {
"description": "Referral detail retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral detail retrieved successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "sent"
},
"sent_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z",
"nullable": true
},
"received_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-30T09:15:00Z",
"nullable": true
},
"processed_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-31T14:45:00Z",
"nullable": true
},
"patient": {
"properties": {
"id": {
"type": "integer",
"example": 15
},
"uuid": {
"type": "string",
"example": "client-uuid-123"
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
}
},
"type": "object"
},
"source_business": {
"properties": {
"id": {
"type": "integer",
"example": 7
},
"name": {
"type": "string",
"example": "Source Clinic"
}
},
"type": "object"
},
"partner_business": {
"properties": {
"id": {
"type": "integer",
"example": 11
},
"name": {
"type": "string",
"example": "Partner Clinic"
}
},
"type": "object"
},
"partner_location": {
"properties": {
"id": {
"type": "integer",
"example": 3
},
"name": {
"type": "string",
"example": "Downtown Location"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "Austin"
},
"state": {
"type": "string",
"example": "TX"
},
"country": {
"type": "string",
"example": "USA"
},
"assigned_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-01T10:00:00Z",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"partner_station": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Intake Station"
},
"description": {
"type": "string",
"example": "Handles new referrals"
},
"assigned_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-01T11:30:00Z",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"form_response": {
"description": "Detailed form response information",
"type": "object"
},
"notes": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "note-uuid-123"
},
"note": {
"type": "string",
"example": "Initial intake call completed"
},
"business": {
"properties": {
"id": {
"type": "integer",
"example": 11
},
"name": {
"type": "string",
"example": "Partner Clinic"
}
},
"type": "object"
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 25
},
"name": {
"type": "string",
"example": "Jane Smith"
},
"email": {
"type": "string",
"example": "jane@example.com"
}
},
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-02T08:45:00Z"
}
},
"type": "object"
}
},
"reports": {
"description": "Reports attached to the form response",
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-5678-90ef-1234-567890abcdef"
},
"title": {
"type": "string",
"example": "MRI Results - Head"
},
"file_url": {
"type": "string",
"example": "https://files.example.com/reports/mri-head-123.pdf"
},
"type": {
"type": "string",
"example": "imaging",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-01-01T10:00:00Z"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization ID header is required"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral not found or not accessible by the business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral submission not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Unexpected error retrieving the referral detail",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to retrieve referral detail at this time"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}/notes": {
"get": {
"tags": [
"Referrals"
],
"summary": "List referral notes",
"description": "Retrieve notes associated with a referral that are visible to the authenticated business",
"operationId": "ea0d8f68f095e4f47e397c6b977aa399",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral submission",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of notes per page (1-100)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "page",
"in": "query",
"description": "Page number for paginated results",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Referral notes retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral notes retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"example": "note-uuid-123"
},
"note": {
"type": "string",
"example": "Initial intake call completed"
},
"business": {
"properties": {
"id": {
"type": "integer",
"example": 11
},
"name": {
"type": "string",
"example": "Partner Clinic"
}
},
"type": "object",
"nullable": true
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 45
},
"name": {
"type": "string",
"example": "Jane Smith"
},
"email": {
"type": "string",
"example": "jane@example.com"
}
},
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-02T08:45:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-02T08:45:00Z"
}
},
"type": "object"
}
},
"meta": {
"description": "Pagination metadata",
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 28
}
},
"type": "object"
},
"links": {
"description": "Pagination links",
"properties": {
"first": {
"type": "string",
"example": "https://app.example.com/api/v1/referrals/{referral_uuid}/notes?page=1"
},
"last": {
"type": "string",
"example": "https://app.example.com/api/v1/referrals/{referral_uuid}/notes?page=2"
},
"next": {
"type": "string",
"example": "https://app.example.com/api/v1/referrals/{referral_uuid}/notes?page=2",
"nullable": true
},
"prev": {
"type": "string",
"example": null,
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization ID header is required"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral not found or not accessible",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral submission not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Unexpected error retrieving notes",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to retrieve referral notes at this time"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Referrals"
],
"summary": "Add a note to a referral submission",
"description": "Add a note to a referral submission from the partner business perspective",
"operationId": "4d57757792fa2ef97d25401e12e7f400",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral submission",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Note content",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"note"
],
"properties": {
"note": {
"description": "Note text to add to the referral",
"type": "string",
"maxLength": 2000,
"example": "Patient confirmed for follow-up appointment next week"
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Note added successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral note added successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"note": {
"type": "string",
"example": "Patient confirmed for follow-up appointment next week"
},
"business": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Partner Clinic"
}
},
"type": "object"
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 25
},
"name": {
"type": "string",
"example": "Jane Smith"
},
"email": {
"type": "string",
"example": "jane@example.com"
}
},
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-02T08:45:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-02T08:45:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization ID header is required"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral not found or not accessible by the business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral submission not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Unexpected error adding the note",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to add note at this time"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}/assign-location": {
"post": {
"tags": [
"Referrals"
],
"summary": "Assign a referral to a partner location",
"description": "Assign a referral submission to a specific partner location and optionally to a station",
"operationId": "7678f0cafc5740c8b968f3590af49453",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral submission",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
}
}
],
"requestBody": {
"description": "Location and station assignment details",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"location_id"
],
"properties": {
"location_id": {
"description": "ID of the partner location to assign the referral to",
"type": "integer",
"example": 5
},
"station_id": {
"description": "Optional ID of the station within the location",
"type": "integer",
"example": 12,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral assigned to location successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral assigned to location successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "sent"
},
"partner_location": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Downtown Location"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "Austin"
},
"state": {
"type": "string",
"example": "TX"
},
"country": {
"type": "string",
"example": "USA"
},
"assigned_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-01T10:00:00Z",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"partner_station": {
"properties": {
"id": {
"type": "integer",
"example": 12
},
"name": {
"type": "string",
"example": "Intake Station"
},
"description": {
"type": "string",
"example": "Handles new referrals"
},
"assigned_at": {
"type": "string",
"format": "date-time",
"example": "2024-11-01T11:30:00Z",
"nullable": true
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Organization header missing or invalid",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Organization ID header is required"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral, location, or station not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral submission not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error or invalid assignment",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Unexpected error assigning the referral",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to assign referral at this time"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}/accept": {
"post": {
"tags": [
"Referrals"
],
"summary": "Accept a received referral",
"description": "Accept a referral that was sent by a partner business",
"operationId": "822e30a2e7695c3939250a00ba89ddaa",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral to accept",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Optional notes",
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"description": "Optional notes about accepting the referral",
"type": "string",
"maxLength": 1000,
"example": "Patient information verified and accepted"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral accepted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral accepted successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "accepted"
},
"processed_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}/reject": {
"post": {
"tags": [
"Referrals"
],
"summary": "Reject a received referral",
"description": "Reject a referral that was sent by a partner business",
"operationId": "d7d28277ab2448f04abb6a94b4ebe996",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral to reject",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Optional reason for rejection",
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"description": "Optional notes about rejecting the referral",
"type": "string",
"maxLength": 1000,
"example": "Unable to accept due to capacity constraints"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral rejected successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral rejected successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "rejected"
},
"processed_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/{referral_uuid}/complete": {
"post": {
"tags": [
"Referrals"
],
"summary": "Complete a referral",
"description": "Mark an accepted referral as completed after processing",
"operationId": "687a44dd5814bded8efd92094183e9d7",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "referral_uuid",
"in": "path",
"description": "UUID of the referral to complete",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Optional completion notes",
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"notes": {
"description": "Optional notes about completing the referral",
"type": "string",
"maxLength": 1000,
"example": "Services rendered and referral closed"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral completed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral completed successfully"
},
"data": {
"properties": {
"uuid": {
"type": "string",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"status": {
"type": "string",
"example": "completed"
},
"processed_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-29T12:30:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Referral not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Referral not found"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/statistics": {
"get": {
"tags": [
"Referrals"
],
"summary": "Get referral statistics",
"description": "Get statistics for referrals sent and received by the business",
"operationId": "eeb26b4533fe20ccfcc85f0a556f601a",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral statistics retrieved successfully"
},
"data": {
"properties": {
"sent": {
"properties": {
"total": {
"type": "integer",
"example": 45
},
"pending": {
"type": "integer",
"example": 5
},
"sent": {
"type": "integer",
"example": 30
},
"received": {
"type": "integer",
"example": 25
},
"accepted": {
"type": "integer",
"example": 20
},
"rejected": {
"type": "integer",
"example": 5
}
},
"type": "object"
},
"received": {
"properties": {
"total": {
"type": "integer",
"example": 30
},
"pending": {
"type": "integer",
"example": 3
},
"sent": {
"type": "integer",
"example": 20
},
"received": {
"type": "integer",
"example": 15
},
"accepted": {
"type": "integer",
"example": 12
},
"rejected": {
"type": "integer",
"example": 3
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/summary": {
"get": {
"tags": [
"Referrals"
],
"summary": "Get referral dashboard summary counters",
"description": "Returns total referrals, acceptance rate, match accuracy, and average time from submission to approval for the authenticated business.",
"operationId": "1b34e5625683064cba8311ff7b047f8c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter submissions created on or after this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date",
"example": "2024-01-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter submissions created on or before this date (YYYY-MM-DD)",
"schema": {
"type": "string",
"format": "date",
"example": "2024-12-31"
}
}
],
"responses": {
"200": {
"description": "Summary counters retrieved successfully"
},
"400": {
"description": "Bad request"
},
"500": {
"description": "Server error"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/referrals/send-form-by-email": {
"post": {
"tags": [
"Referrals"
],
"summary": "Send referral form link to users by email",
"description": "Send a referral form link to multiple users by their email addresses. If a client doesn't exist, it will be created with information extracted from the email address. Does not create form requests - just sends the form link directly.",
"operationId": "d53401229e21c8ffa9ffd3281ef9d9cd",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID (Business ID)",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Referral form email data",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"emails",
"form_id"
],
"properties": {
"emails": {
"description": "Array of email addresses to send the referral form to",
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"example": [
"user1@example.com",
"user2@example.com"
]
},
"form_id": {
"description": "UUID of the referral form to send",
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"message": {
"description": "Optional custom message to include in the email",
"type": "string",
"maxLength": 1000,
"example": "Please complete this referral form."
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Referral form emails sent",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Referral form emails processed"
},
"data": {
"properties": {
"form_url": {
"type": "string",
"example": "https://app.example.com/forms/form-uuid-123"
},
"sent": {
"type": "array",
"items": {
"properties": {
"email": {
"type": "string",
"example": "user1@example.com"
},
"client_id": {
"type": "integer",
"example": 456
},
"status": {
"type": "string",
"example": "sent"
}
},
"type": "object"
}
},
"failed": {
"type": "array",
"items": {
"properties": {
"email": {
"type": "string",
"example": "user2@example.com"
},
"reason": {
"type": "string",
"example": "Failed to send email"
}
},
"type": "object"
}
},
"total_requested": {
"type": "integer",
"example": 2
},
"total_sent": {
"type": "integer",
"example": 1
},
"total_failed": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Invalid request - Form not a referral type or business header missing",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form must be of type 'referral'"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Form not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Form not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/roles": {
"get": {
"tags": [
"Role Permissions"
],
"summary": "Get list of all available roles",
"operationId": "514e8650d35d9a6ea301fb8222a9608a",
"responses": {
"200": {
"description": "List of all available roles",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "BUSINESS_ADMIN"
},
"display_name": {
"type": "string",
"example": "Business Administrator"
},
"description": {
"type": "string",
"example": "Full access to all business operations"
}
},
"type": "object"
}
},
"message": {
"type": "string",
"example": "Roles retrieved successfully"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/role-permissions": {
"get": {
"tags": [
"Role Permissions"
],
"summary": "Get role permissions based on business, location, and station",
"operationId": "df09fd036fe589f7c6c6091c5ea15294",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Station ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Role permissions retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"$ref": "#/components/schemas/RolePermission"
},
"message": {
"type": "string",
"example": "Role Permission retrieved"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Not have access",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Not have access"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"error": {
"type": "string",
"example": "Unauthorized"
},
"message": {
"type": "string",
"example": "No organization found for this account"
}
},
"type": "object"
}
}
}
}
}
}
},
"/api/v2/permissions/roles": {
"get": {
"tags": [
"Role Permission v2 Team Member Configs"
],
"summary": "List organization roles (read-only)",
"operationId": "076e81cc43fad90b43dc548934301e86",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Success"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"key": {
"type": "string",
"example": "organization_admin"
},
"name": {
"type": "string",
"example": "Admin"
},
"description": {
"type": "string",
"example": "Administrative access to organization settings."
},
"type": {
"type": "string",
"example": "default"
},
"total_modules": {
"type": "integer",
"example": 13
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/roles/{role}": {
"get": {
"tags": [
"Role Permission v2 Team Member Configs"
],
"summary": "Get organization role detail (read-only)",
"operationId": "0d650178ee5365f38a89bf5114971e73",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "role",
"in": "path",
"description": "Role ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Success"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"type": {
"type": "string",
"example": "default"
},
"key": {
"type": "string",
"example": "organization_admin"
},
"name": {
"type": "string",
"example": "Admin"
},
"description": {
"type": "string",
"example": "Administrative access to organization settings."
},
"modules": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "referral"
},
"name": {
"type": "string",
"example": "Referral"
},
"description": {
"type": "string",
"example": "Manage patient referrals and referral tracking."
},
"permissions": {
"type": "array",
"items": {
"properties": {
"permissionKey": {
"type": "string",
"example": "referral:view"
},
"permissionName": {
"type": "string",
"example": "View Referral"
},
"moduleKey": {
"type": "string",
"example": "referral"
},
"moduleName": {
"type": "string",
"example": "Referral"
},
"supports_location_selection": {
"type": "boolean",
"example": false
},
"supports_provider_selection": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"is_active": {
"type": "boolean",
"example": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/my-permissions": {
"get": {
"tags": [
"Role Permission v2 Runtime Checks"
],
"summary": "Get current user permissions for the current workspace context",
"operationId": "3491ba29446d8d5be691ea3317ce3763",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Optional Location ID for scoping",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Optional Station ID for scoping",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Success"
},
"data": {
"properties": {
"organizationId": {
"type": "integer",
"example": 1
},
"role": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"name": {
"type": "string",
"example": "Admin"
},
"type": {
"type": "string",
"example": "default"
}
},
"type": "object"
},
"sidebars": {
"type": "array",
"items": {
"type": "string",
"example": "workspace:location"
}
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"example": "referral:view"
}
},
"scopes": {
"properties": {
"locations": {
"description": "location_id → array of allowed permission keys",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "integer",
"example": 5
}
}
},
"providers": {
"description": "provider_id → array of allowed permission keys",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "integer",
"example": 42
}
}
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/all": {
"get": {
"tags": [
"Role Permission v2 Team Member Configs"
],
"summary": "Get all available modules and permissions catalog",
"operationId": "6b0f9f3d6b3f8bc6e328e604ca84d105",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Success"
},
"data": {
"description": "module_key → array of permission keys",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"example": "referral:view"
}
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/setting/roles": {
"get": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "List organization roles for settings",
"operationId": "3c3b1a27fa406c7d916887ef01f8a72c",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Success"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"key": {
"type": "string",
"example": "organization_admin"
},
"name": {
"type": "string",
"example": "Admin"
},
"description": {
"type": "string",
"example": "Administrative access to organization settings."
},
"type": {
"type": "string",
"example": "default"
},
"total_modules": {
"type": "integer",
"example": 13
},
"member_count": {
"type": "integer",
"example": 5
},
"modules": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "referral"
},
"name": {
"type": "string",
"example": "Referral"
},
"description": {
"type": "string",
"example": "Manage patient referrals and referral tracking."
}
},
"type": "object"
}
},
"is_active": {
"type": "boolean",
"example": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 100
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 7
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "Create a custom organization role",
"operationId": "c581c72b0df573a92f90ebc88f412eee",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Custom Support"
},
"description": {
"type": "string",
"example": "Custom role for support team"
},
"is_active": {
"type": "boolean",
"example": true
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"example": "referral:view"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Role created successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/setting/roles/{role}": {
"get": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "Get organization role detail for settings",
"operationId": "0aa64edac2d17fe8083fb06d48435d96",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "role",
"in": "path",
"description": "Role ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Success"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"type": {
"type": "string",
"example": "default"
},
"key": {
"type": "string",
"example": "organization_admin"
},
"name": {
"type": "string",
"example": "Admin"
},
"description": {
"type": "string",
"example": "Administrative access to organization settings."
},
"member_count": {
"type": "integer",
"example": 5
},
"members": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john.doe@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"status": {
"type": "string",
"example": "active"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"modules": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "referral"
},
"name": {
"type": "string",
"example": "Referral"
},
"description": {
"type": "string",
"example": "Manage patient referrals and referral tracking."
},
"permissions": {
"type": "array",
"items": {
"properties": {
"permissionKey": {
"type": "string",
"example": "referral:view"
},
"permissionName": {
"type": "string",
"example": "View Referral"
},
"moduleKey": {
"type": "string",
"example": "referral"
},
"moduleName": {
"type": "string",
"example": "Referral"
},
"isActive": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"is_active": {
"type": "boolean",
"example": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "Update an organization role",
"operationId": "89662005326b7bbb85d6bece13fc3351",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "role",
"in": "path",
"description": "Role ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string",
"example": "Updated Admin"
},
"description": {
"type": "string",
"example": "Updated description for admin role"
},
"is_active": {
"type": "boolean",
"example": true
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"example": "referral:view"
}
},
"members": {
"type": "array",
"items": {
"type": "string",
"example": "1"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Role updated successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "Delete a custom organization role",
"operationId": "f9fb9c9b86a04b4c3c8f1bba8ff0ef1b",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "role",
"in": "path",
"description": "Role ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"delete_team_members": {
"type": "boolean",
"example": false
},
"role_id_to_assign_existing_team_members": {
"type": "integer",
"example": 12,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization role deleted successfully"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/setting/roles/{role}/modules/{module_key}": {
"post": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "Update role permissions for a specific module",
"operationId": "c240a78b5d72f38b65ff83e99aee8e5b",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "role",
"in": "path",
"description": "Role ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "module_key",
"in": "path",
"description": "Module Key",
"required": true,
"schema": {
"type": "string",
"example": "referral"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"permissions": {
"type": "array",
"items": {
"type": "string",
"example": "referral:view"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Module permissions updated successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/permissions/setting/roles/bulk-delete": {
"delete": {
"tags": [
"Role Permissions v2 Settings"
],
"summary": "Bulk delete custom organization roles",
"operationId": "a1ecf84c05080760d275e39f05e70476",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"role_ids"
],
"properties": {
"role_ids": {
"type": "array",
"items": {
"type": "integer",
"example": 10
}
},
"delete_team_members": {
"type": "boolean",
"example": false
},
"role_id_to_assign_existing_team_members": {
"type": "integer",
"example": 12,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Roles deleted successfully"
},
"data": {
"properties": {
"skipped_count": {
"type": "integer",
"example": 1
},
"succeed_count": {
"type": "integer",
"example": 2
},
"failed_count": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members": {
"get": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "List team members",
"description": "Returns a paginated list of organization team members (excluding owners)",
"operationId": "69456bf92ff8c7a4649260e09941f3f8",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15
}
}
],
"responses": {
"200": {
"description": "Team members retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberListResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Add a team member",
"description": "Add a new team member to the organization with specific role and permissions",
"operationId": "0173b9e82b7285cc106a4d27dbb4d0b1",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberStoreRequest"
}
}
}
},
"responses": {
"200": {
"description": "Team member added successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberSingleResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"409": {
"description": "Conflict - User already a member"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/location/{locationId}": {
"get": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "List team members for a location",
"operationId": "59d29da92a1e0309c635022e2a5388ed",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "locationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "per_page",
"in": "query",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Team members retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberListResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Add team member for location",
"operationId": "a8d3f863e48b4e796b57201e594125dd",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "locationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberScopedStoreRequest"
}
}
}
},
"responses": {
"200": {
"description": "Team member added successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberSingleResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/station/{stationId}": {
"get": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "List team members for a station",
"operationId": "cce3639698407dca3d40fbe942aa3218",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "stationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Team members retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberListResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Add team member for station",
"operationId": "fed90893b5b45d99376e456666e39214",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "stationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberScopedStoreRequest"
}
}
}
},
"responses": {
"200": {
"description": "Team member added successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberSingleResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/{orgUser}": {
"get": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Get a team member detail",
"description": "Returns a team member payload shaped for edit forms. Permissions follow the same structure as the main create/update payload.",
"operationId": "22686d30d667625111a7dab1a48f5477",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "orgUser",
"in": "path",
"description": "Organization User ID",
"required": true,
"schema": {
"type": "integer",
"example": 15
}
}
],
"responses": {
"200": {
"description": "Team member retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberDetailResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Remove a team member",
"description": "Remove a team member from the organization",
"operationId": "c313206ec3a079073db38c8722714e10",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "orgUser",
"in": "path",
"description": "Organization User ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Team member removed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberDeleteResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Update a team member",
"description": "Update role, status, or permissions of an existing team member",
"operationId": "dbc6c6929a23578679b4129286d1dd6e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "orgUser",
"in": "path",
"description": "Organization User ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Team member updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberSingleResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/location-station/{locationStationId}": {
"get": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "List team members for a location station",
"operationId": "45419dc7849199b9bf6bf8cc9565af33",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "locationStationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Team members retrieved successfully"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Add team member for location station",
"operationId": "5b2125f1c490965395647adb9ea47e03",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "locationStationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberPayload"
}
}
}
},
"responses": {
"200": {
"description": "Team member added successfully"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/location/{locationId}/{orgUser}": {
"delete": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Remove team member from location",
"operationId": "8785df54d7fb0c7769ffcc9d44054396",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true
},
{
"name": "locationId",
"in": "path",
"required": true
},
{
"name": "orgUser",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Team member removed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberDeleteResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Update team member for location",
"operationId": "b05027ee26c2e81d11519d78423ad624",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "locationId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "orgUser",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberScopedUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Team member updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberSingleResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/station/{stationId}/{orgUser}": {
"delete": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Remove team member from station",
"operationId": "395de284728bc2dd8351bb8724f20aec",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true
},
{
"name": "stationId",
"in": "path",
"required": true
},
{
"name": "orgUser",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Team member removed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberDeleteResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Update team member for station",
"operationId": "c88a6d1c22b1946ea51c60e8f2d2e741",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true
},
{
"name": "stationId",
"in": "path",
"required": true
},
{
"name": "orgUser",
"in": "path",
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberScopedUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Team member updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamMemberSingleResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/team-members/location-station/{locationStationId}/{orgUser}": {
"delete": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Remove team member from location station",
"operationId": "63b30eea99c9b0ac54cd95c57f5fdbb8",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true
},
{
"name": "locationStationId",
"in": "path",
"required": true
},
{
"name": "orgUser",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Removed"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Role Permission v2 - Team members"
],
"summary": "Update team member for location station",
"operationId": "7428e2ab4ff096caf371b4f77bd94973",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"required": true
},
{
"name": "locationStationId",
"in": "path",
"required": true
},
{
"name": "orgUser",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Updated"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/custom": {
"get": {
"tags": [
"Booking Link Requests"
],
"summary": "Get all booking link requests for the authenticated business",
"description": "Retrieves all booking link requests for the authenticated business, including related client requests, clients, and schedule links",
"operationId": "getBookingLinkRequests",
"responses": {
"200": {
"description": "Booking Request List Response",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "success"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BookingLinkRequestResource"
}
},
"message": {
"type": "string",
"example": "Booking Request List Retrieved Successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"error_code": {
"type": "string",
"example": "UNAUTHORIZED"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Booking Link Requests"
],
"summary": "Create a new booking link request",
"description": "Creates a new booking link request with workspace selections and client assignments. Validates workspace selections and client assignments before creation.",
"operationId": "createBookingLinkRequest",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBookingLinkRequest"
}
}
}
},
"responses": {
"201": {
"description": "Booking Link Request created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "success"
},
"data": {
"$ref": "#/components/schemas/BookingLinkRequestResource"
},
"message": {
"type": "string",
"example": "Booking Link Request created successfully"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookingLinkRequestValidationError"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"error_code": {
"type": "string",
"example": "UNAUTHORIZED"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/custom/{id}": {
"get": {
"tags": [
"Booking Link Requests"
],
"summary": "Get Detail Of Request",
"description": "Retrieves the current booking links information. Useful for editing or displaying current configuration.",
"operationId": "getBookingRequestDetail",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the booking link request",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Booking Link Request detail",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "string",
"example": "success"
},
"data": {
"$ref": "#/components/schemas/BookingLinkRequestResource"
},
"message": {
"type": "string",
"example": "Booking Link Request detail retrieved successfully"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized access to booking link request",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized access to booking link request"
},
"error_code": {
"type": "string",
"example": "UNAUTHORIZED"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Booking link request not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Resource not found"
},
"error_code": {
"type": "string",
"example": "NOT_FOUND"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/organization/schedule-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create organization schedule link",
"description": "Get existing custom schedule link for the organization or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateOrganizationScheduleLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Organization schedule link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update organization schedule link",
"description": "Get or create organization schedule link and then update it with provided data",
"operationId": "updateOrganizationScheduleLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Organization schedule link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/organization/walk-in-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create organization walk-in link",
"description": "Get existing custom walk-in link for the organization or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateOrganizationWalkInLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Organization walk-in link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update organization walk-in link",
"description": "Get or create organization walk-in link and then update it with provided data",
"operationId": "updateOrganizationWalkInLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Organization walk-in link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/organization/general-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create organization General link",
"description": "Get existing custom General link for the organization or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateOrganizationGeneralLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Organization general link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update organization general link",
"description": "Get or create organization general link and then update it with provided data",
"operationId": "updateOrganizationGeneralLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Organization general link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/locations/{id}/schedule-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create location schedule link",
"description": "Get existing custom schedule link for a specific location or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateLocationScheduleLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Location schedule link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update location schedule link",
"description": "Get or create location schedule link and then update it with provided data",
"operationId": "updateLocationScheduleLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Location schedule link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/locations/{id}/walk-in-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create location walk-in link",
"description": "Get existing custom walk-in link for a specific location or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateLocationWalkInLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Location walk-in link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update location walk-in link",
"description": "Get or create location walk-in link and then update it with provided data",
"operationId": "updateLocationWalkInLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Location walk-in link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/locations/{id}/general-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create location general link",
"description": "Get existing custom general link for a specific location or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateLocationGeneralLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Location general link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update location general link",
"description": "Get or create location general link and then update it with provided data",
"operationId": "updateLocationGeneralLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 123
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Location general link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/stations/{id}/schedule-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create station schedule link",
"description": "Get existing custom schedule link for a specific station or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateStationScheduleLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "location_id",
"in": "query",
"description": "Location ID - if provided, creates a LocationStation link instead of a Station link",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Station schedule link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update station schedule link",
"description": "Get or create station schedule link and then update it with provided data",
"operationId": "updateStationScheduleLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "location_id",
"in": "query",
"description": "Location ID - if provided, updates a LocationStation link instead of a Station link",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Station schedule link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/stations/{id}/walk-in-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create station walk-in link",
"description": "Get existing custom walk-in link for a specific station or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateStationWalkInLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "location_id",
"in": "query",
"description": "Location ID - if provided, creates a LocationStation link instead of a Station link",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Station walk-in link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update station walk-in link",
"description": "Get or create station walk-in link and then update it with provided data",
"operationId": "updateStationWalkInLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "location_id",
"in": "query",
"description": "Location ID - if provided, updates a LocationStation link instead of a Station link",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Station walk-in link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/stations/{id}/general-link": {
"get": {
"tags": [
"Schedule Links"
],
"summary": "Get or create station general link",
"description": "Get existing custom general link for a specific station or create a new one with intelligent defaults. No payload required.",
"operationId": "getOrCreateStationGeneralLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "location_id",
"in": "query",
"description": "Location ID - if provided, creates a LocationStation link instead of a Station link",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Station general link retrieved or created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"tags": [
"Schedule Links"
],
"summary": "Update station general link",
"description": "Get or create station general link and then update it with provided data",
"operationId": "updateStationGeneralLink",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "id",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 456
}
},
{
"name": "location_id",
"in": "query",
"description": "Location ID - if provided, updates a LocationStation link instead of a Station link",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"requestBody": {
"description": "Custom link update data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "Station general link updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleLinkResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/booking-links/check-availability": {
"post": {
"tags": [
"Schedule Links"
],
"summary": "Check booking link path availability",
"description": "Check if a booking link path is available for a new booking link",
"operationId": "checkBookingLinkAvailability",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "Booking link path and optional exclude ID",
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"custom_path"
],
"properties": {
"custom_path": {
"type": "string",
"example": "my-schedule"
},
"exclude_id": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Path availability checked",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Path availability checked"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services": {
"get": {
"tags": [
"Service"
],
"summary": "List all services for the current organization",
"operationId": "fbe5641799866689041fdf967803c27b",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "ids",
"in": "query",
"description": "Filter services by IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "search",
"in": "query",
"description": "Search term to filter services by name or description",
"required": false,
"schema": {
"type": "string",
"example": "consultation"
}
},
{
"name": "location",
"in": "query",
"description": "Filter services by location IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station",
"in": "query",
"description": "Filter services by station IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "roles",
"in": "query",
"description": "Filter services by team member roles (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "Doctor,Nurse"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field (name, time_in_minute, created_at)",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (asc, desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "from",
"in": "query",
"description": "Filter services created from this date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2023-01-01"
}
},
{
"name": "to",
"in": "query",
"description": "Filter services created until this date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2023-12-31"
}
},
{
"name": "is_available",
"in": "query",
"description": "Filter services by availability status",
"required": false,
"schema": {
"type": "boolean",
"example": true
}
},
{
"name": "is_visible",
"in": "query",
"description": "Filter services by visibility status",
"required": false,
"schema": {
"type": "boolean",
"example": true
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter services by location ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter services by station ID",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "exclude_location_id",
"in": "query",
"description": "Exclude services that are already assigned to this location ID (useful for 'Add Service' dropdowns)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "exclude_station_id",
"in": "query",
"description": "Exclude services assigned to this station. When used with exclude_location_id, this is the station_id; when used alone, this is the location_station_id",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "methods",
"in": "query",
"description": "Filter services by appointment method names or IDs (comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "in-person,video,2"
}
},
{
"name": "status",
"in": "query",
"description": "Filter services by status (active or inactive)",
"required": false,
"schema": {
"type": "string",
"enum": [
"active",
"inactive"
],
"example": "active"
}
},
{
"name": "basic",
"in": "query",
"description": "If true, returns only id and name fields",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "include",
"in": "query",
"description": "Include additional data (comma-separated). Available options: forms, locations, stations",
"required": false,
"schema": {
"type": "string",
"example": "forms,locations,stations"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (1-100, default: 15)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
}
],
"responses": {
"200": {
"description": "List of services",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"business_id": {
"type": "integer"
},
"time_in_minute": {
"type": "integer"
},
"is_available": {
"type": "boolean"
},
"auto_approve": {
"type": "boolean"
},
"is_visible": {
"type": "boolean"
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
},
"forms": {
"description": "Included when include=forms",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string"
}
},
"type": "object"
}
},
"locations": {
"description": "Included when include=locations",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"address": {
"type": "string"
}
},
"type": "object"
}
},
"stations": {
"description": "Included when include=stations",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Service"
],
"summary": "Create a new service",
"operationId": "c66544f7140a6ced98d743220933d04d",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"time_in_minute",
"appointment_methods"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"time_in_minute": {
"type": "integer"
},
"appointment_methods": {
"type": "array",
"items": {
"type": "integer"
}
},
"is_available": {
"type": "boolean",
"default": true
},
"auto_approve": {
"type": "boolean",
"default": false
},
"is_visible": {
"type": "boolean",
"default": true
},
"apply_to_all_locations": {
"description": "If true, service applies to all locations and stations",
"type": "boolean",
"default": false
},
"location_selections": {
"description": "Array of location selections (only used when apply_to_all_locations is false)",
"type": "array",
"items": {
"properties": {
"location_id": {
"type": "integer"
},
"all_stations": {
"description": "If true, includes all stations in this location",
"type": "boolean"
},
"station_ids": {
"description": "Specific station IDs (only used when all_stations is false)",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Service created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service created successfully"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"business_id": {
"type": "integer"
},
"time_in_minute": {
"type": "integer"
},
"is_available": {
"type": "boolean"
},
"auto_approve": {
"type": "boolean"
},
"is_visible": {
"type": "boolean"
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services/{id}": {
"get": {
"tags": [
"Service"
],
"summary": "Get a single service by ID",
"operationId": "8ce137110f16c393fc4d592555033e72",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "basic",
"in": "query",
"description": "If true, returns only id and name fields",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "include",
"in": "query",
"description": "Include additional data (comma-separated). Available options: forms, locations, stations",
"required": false,
"schema": {
"type": "string",
"example": "forms,locations,stations"
}
}
],
"responses": {
"200": {
"description": "Service details",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service retrieved successfully"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"business_id": {
"type": "integer"
},
"time_in_minute": {
"type": "integer"
},
"is_available": {
"type": "boolean"
},
"auto_approve": {
"type": "boolean"
},
"is_visible": {
"type": "boolean"
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
},
"forms": {
"description": "Included when include=forms",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string"
}
},
"type": "object"
}
},
"locations": {
"description": "Included when include=locations",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"address": {
"type": "string"
}
},
"type": "object"
}
},
"stations": {
"description": "Included when include=stations",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"type": "object"
}
},
"apply_to_all_locations": {
"description": "Whether the service applies to all locations",
"type": "boolean"
},
"location_selections": {
"description": "Location selection details",
"type": "array",
"items": {
"properties": {
"location_id": {
"type": "integer"
},
"location_name": {
"type": "string"
},
"all_stations": {
"type": "boolean"
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"total_locations": {
"description": "Total number of locations where this service is available",
"type": "integer"
},
"total_stations": {
"description": "Total number of stations where this service is available",
"type": "integer"
},
"average_rating": {
"description": "Average rating of the service",
"type": "number",
"format": "float"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Service"
],
"summary": "Update a service (full or partial update)",
"description": "Updates a service. Can be used for both full and partial updates. If location/station fields are provided, they will be processed; otherwise, only basic service fields will be updated.",
"operationId": "2095a477ae4f3a73ad2540f67fa2358e",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"description": "All fields are optional. Only provided fields will be updated.",
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Service name",
"type": "string"
},
"description": {
"description": "Service description",
"type": "string",
"nullable": true
},
"time_in_minute": {
"description": "Duration in minutes",
"type": "integer"
},
"appointment_methods": {
"description": "Array of appointment method IDs",
"type": "array",
"items": {
"type": "integer"
}
},
"is_available": {
"description": "Whether the service is available",
"type": "boolean"
},
"auto_approve": {
"description": "Whether appointments are auto-approved",
"type": "boolean"
},
"is_visible": {
"description": "Whether the service is visible",
"type": "boolean"
},
"apply_to_all_locations": {
"description": "If true, service applies to all locations and stations",
"type": "boolean"
},
"location_selections": {
"description": "Array of location selections (only used when apply_to_all_locations is false)",
"type": "array",
"items": {
"properties": {
"location_id": {
"description": "Location ID",
"type": "integer"
},
"all_stations": {
"description": "If true, includes all stations in this location",
"type": "boolean"
},
"station_ids": {
"description": "Specific station IDs (only used when all_stations is false)",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Service updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service updated successfully"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"business_id": {
"type": "integer"
},
"time_in_minute": {
"type": "integer"
},
"is_available": {
"type": "boolean"
},
"auto_approve": {
"type": "boolean"
},
"is_visible": {
"type": "boolean"
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
},
"apply_to_all_locations": {
"type": "boolean"
},
"location_selections": {
"type": "array",
"items": {
"properties": {
"location_id": {
"type": "integer"
},
"location_name": {
"type": "string"
},
"all_stations": {
"type": "boolean"
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"total_locations": {
"type": "integer"
},
"total_stations": {
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Service not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Service not found."
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Service"
],
"summary": "Delete a service",
"operationId": "32c6c5b52cbc0cfc238bb7c5d0c13ee8",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Service deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service deleted successfully"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/appointment-methods": {
"get": {
"tags": [
"Service"
],
"summary": "List all appointment methods",
"operationId": "8283e26f99de7949d47af92a82e092b9",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "search",
"in": "query",
"description": "Search appointment methods by name or description",
"required": false,
"schema": {
"type": "string",
"example": "virtual"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort by field",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"created_at"
],
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (1-100). If not provided, returns all data.",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 10
}
}
],
"responses": {
"200": {
"description": "List of appointment methods",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Appointment methods retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
},
"meta": {
"description": "Pagination metadata (only when per_page is provided)",
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 3
},
"per_page": {
"type": "integer",
"example": 10
},
"total": {
"type": "integer",
"example": 25
},
"from": {
"type": "integer",
"example": 1
},
"to": {
"type": "integer",
"example": 10
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services/{id}/locations-stations": {
"patch": {
"tags": [
"Service"
],
"summary": "Update location-station assignments for a service",
"operationId": "d52c68ee9f798f2c89747bab27d64298",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"apply_to_all_locations": {
"description": "If true, service applies to all locations and stations",
"type": "boolean"
},
"location_selections": {
"description": "Array of location selections (only used when apply_to_all_locations is false)",
"type": "array",
"items": {
"properties": {
"location_id": {
"type": "integer"
},
"all_stations": {
"description": "If true, includes all stations in this location",
"type": "boolean"
},
"station_ids": {
"description": "Specific station IDs (only used when all_stations is false)",
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Location-station assignments updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Location-station assignments updated successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services/{id}/station": {
"get": {
"tags": [
"Service"
],
"summary": "Get all stations linked to a service",
"operationId": "b6dc96e4e1b852bfe2ad5bfffcc7aa9f",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Service ID",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "List of stations linked to the service",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service stations retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"image": {
"type": "string",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"average_rating": {
"type": "number",
"format": "float"
},
"locations": {
"description": "Included when include=locations",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
},
"service_providers": {
"description": "Included when include=service_providers",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"role": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Service not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Service not found."
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services/bulk-delete": {
"post": {
"tags": [
"Service"
],
"summary": "Bulk delete services or service assignments",
"description": "Delete multiple services or remove service assignments from specific locations/stations/location-stations. When location_id, station_id, or location_station_id is provided, only removes the service assignments (ServiceOwner records) without deleting the actual services. Uses soft delete for services to maintain data integrity.",
"operationId": "4baeb09f666144b9600ada0f72d24f5e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "location_id",
"in": "query",
"description": "Filter by location ID (removes service assignments from this location only)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "station_id",
"in": "query",
"description": "Filter by station ID (removes service assignments from this station only)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "location_station_id",
"in": "query",
"description": "Filter by location-station ID (removes service assignments from this specific location-station combination only)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids"
],
"properties": {
"service_ids": {
"description": "Array of service IDs to delete or remove assignments for",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 Services deleted successfully!"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services/bulk-update-auto-approve": {
"post": {
"tags": [
"Service"
],
"summary": "Bulk update auto approve setting for services at business level",
"description": "Update the auto approve setting for multiple services at the business level (base service configuration)",
"operationId": "0cfeec902518b6360e4a8d7d72a39bda",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids",
"auto_approve"
],
"properties": {
"service_ids": {
"description": "Array of service IDs to update auto approve setting for",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"auto_approve": {
"description": "Whether appointments should be auto-approved",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services auto approve setting updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 services auto-approve updated successfully"
},
"data": {
"properties": {
"updated_count": {
"type": "integer",
"example": 5
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/locations/{locationId}/services/bulk-update-auto-approve": {
"post": {
"tags": [
"Service"
],
"summary": "Bulk update auto approve setting for services at location level",
"description": "Update the auto approve setting for multiple services at a specific location",
"operationId": "8a229ea981aebb41404ad8fa4cdd39ff",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "locationId",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids",
"auto_approve"
],
"properties": {
"service_ids": {
"description": "Array of service IDs to update auto approve setting for",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"auto_approve": {
"description": "Whether appointments should be auto-approved at this location",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services auto approve setting updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 services auto-approve updated successfully for location"
},
"data": {
"properties": {
"updated_count": {
"type": "integer",
"example": 5
},
"location_id": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Location not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/locations/{locationId}/stations/{stationId}/services/bulk-update-auto-approve": {
"post": {
"tags": [
"Service"
],
"summary": "Bulk update auto approve setting for services at location-station level",
"description": "Update the auto approve setting for multiple services at a specific location-station combination",
"operationId": "23f1664c23e3099f14cd7e2c4ccc89e6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "locationId",
"in": "path",
"description": "Location ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "stationId",
"in": "path",
"description": "Station ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_ids",
"auto_approve"
],
"properties": {
"service_ids": {
"description": "Array of service IDs to update auto approve setting for",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"auto_approve": {
"description": "Whether appointments should be auto-approved at this location-station",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Services auto approve setting updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 services auto-approve updated successfully for location-station"
},
"data": {
"properties": {
"updated_count": {
"type": "integer",
"example": 5
},
"location_id": {
"type": "integer",
"example": 1
},
"station_id": {
"type": "integer",
"example": 1
},
"location_station_id": {
"type": "integer",
"example": 5
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Location, Station, or LocationStation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Location-Station combination not found"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/services/{serviceId}/bulk-assign-forms": {
"post": {
"tags": [
"Service"
],
"summary": "Bulk assign forms to a service",
"description": "Assign multiple forms to a specific service",
"operationId": "c3f416370f42bcb774321dd258dd04d7",
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "Service ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"form_ids"
],
"properties": {
"form_ids": {
"description": "Array of form UUIDs to assign",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"type": "object"
},
"example": {
"form_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001"
]
}
}
}
},
"responses": {
"200": {
"description": "Forms assigned successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "2 forms assigned to service successfully"
},
"data": {
"properties": {
"updated_count": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Service not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Service not found"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Failed to assign forms"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/stations": {
"get": {
"tags": [
"Station"
],
"summary": "List all stations for the current organization",
"operationId": "629f24bbe71670f4fec1704222c32c74",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID (optional - if provided, filters stations by location)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "ids",
"in": "query",
"description": "Filter stations by IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "search",
"in": "query",
"description": "Search term to filter stations by name or description",
"required": false,
"schema": {
"type": "string",
"example": "reception"
}
},
{
"name": "location",
"in": "query",
"description": "Filter stations by location IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "roles",
"in": "query",
"description": "Filter stations by team member roles (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "Doctor,Nurse"
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort results by field (name, created_at)",
"required": false,
"schema": {
"type": "string",
"example": "name"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction (asc, desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
},
{
"name": "from",
"in": "query",
"description": "Filter stations created from this date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2023-01-01"
}
},
{
"name": "to",
"in": "query",
"description": "Filter stations created until this date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2023-12-31"
}
},
{
"name": "basic",
"in": "query",
"description": "If true, returns only id and name fields",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of additional fields to include (e.g., basic_services,custom_links)",
"required": false,
"schema": {
"type": "string",
"example": "basic_services,custom_links"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (1-100, default: 15)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "all",
"in": "query",
"description": "If true, returns all stations without pagination and only basic fields (id, name, is_active). Overrides per_page and basic parameters.",
"required": false,
"schema": {
"type": "boolean",
"example": true
}
}
],
"responses": {
"200": {
"description": "List of stations",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Stations retrieved successfully"
},
"data": {
"type": "array",
"items": {}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Station"
],
"summary": "Create a new station",
"operationId": "1ee0821464c435173e6a77a0468c3c70",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID (optional - if not provided, location should be specified in request body)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name",
"location_id"
],
"properties": {
"name": {
"type": "string"
},
"image": {
"type": "string",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"service_provider_first_name": {
"type": "string",
"nullable": true
},
"service_provider_last_name": {
"type": "string",
"nullable": true
},
"service_provider_email": {
"type": "string",
"format": "email",
"nullable": true
},
"service_provider_phone": {
"type": "string",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Station created successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Station created successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/stations/{id}": {
"get": {
"tags": [
"Station"
],
"summary": "Get a single station by ID",
"operationId": "780d935702eb33ca9670b6f1a0e2b6b0",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID (optional - if provided, filters stations by location)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "basic",
"in": "query",
"description": "If true, returns only id and name fields",
"required": false,
"schema": {
"type": "boolean",
"example": false
}
},
{
"name": "include",
"in": "query",
"description": "Comma-separated list of additional fields to include (e.g., basic_services,custom_links)",
"required": false,
"schema": {
"type": "string",
"example": "basic_services,custom_links"
}
}
],
"responses": {
"200": {
"description": "Station details",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Station retrieved successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Station not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Station"
],
"summary": "Update a station",
"operationId": "b84b3e9bd03d2d816715010d0f86c4d6",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID (optional - if provided, filters stations by location)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"image": {
"type": "string",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"is_active": {
"description": "Station status at the specified location (requires X-locationId header)",
"type": "boolean",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Station updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Station updated successfully"
},
"data": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Station not found"
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Station"
],
"summary": "Delete a station",
"operationId": "bc1afeb6e8d868bfafa2d9ed96c1ffa1",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID (optional - if provided, filters stations by location)",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "Station deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Station deleted successfully"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Station not found"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/stations/{id}/service": {
"post": {
"tags": [
"Station"
],
"summary": "Add or update a service at a station",
"description": "Adds a new service to a station or updates an existing service if it's already attached. This is an upsert operation.",
"operationId": "f5017840db1370ba6de893fdefdc5fc5",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"service_id",
"time_in_minute"
],
"properties": {
"service_id": {
"description": "ID of the service to add/update",
"type": "integer"
},
"time_in_minute": {
"description": "Duration of the service in minutes",
"type": "integer",
"minimum": 1
},
"is_available": {
"description": "Whether the service is available at this station",
"type": "boolean",
"default": true
},
"auto_approve": {
"description": "Whether appointments are auto-approved",
"type": "boolean",
"default": false
},
"is_visible": {
"description": "Whether the service is visible",
"type": "boolean",
"default": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Service added or updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Service added to station successfully"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Station not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Station not found."
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed."
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/stations/{id}/services": {
"get": {
"tags": [
"Station"
],
"summary": "Get all services available at a station",
"operationId": "a158db3dabd586fe9cc47e8b1ef939d7",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"responses": {
"200": {
"description": "List of services available at the station",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Services retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"business_id": {
"type": "integer"
},
"time_in_minute": {
"type": "integer"
},
"is_available": {
"type": "boolean"
},
"auto_approve": {
"type": "boolean"
},
"is_visible": {
"type": "boolean"
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/stations/bulk-delete": {
"post": {
"tags": [
"Station"
],
"summary": "Bulk delete stations",
"description": "Delete multiple stations by their IDs",
"operationId": "b7dfd3a47208fe023710a18a7ee2ff45",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids"
],
"properties": {
"station_ids": {
"description": "Array of station IDs to delete",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Stations deleted successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 stations deleted successfully!"
},
"data": {
"properties": {
"deleted_count": {
"type": "integer",
"example": 5
},
"not_found_count": {
"type": "integer",
"example": 0
},
"deleted_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"not_found_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/stations/bulk-assign-locations": {
"post": {
"tags": [
"Station"
],
"summary": "Bulk assign stations to locations",
"description": "Assign multiple stations to multiple locations",
"operationId": "3b0360352b38b49baafc35ff181b3a0e",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"station_ids",
"location_ids"
],
"properties": {
"station_ids": {
"description": "Array of station IDs",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"location_ids": {
"description": "Array of location IDs to assign to",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"replace": {
"description": "Whether to replace existing locations or add to them",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Stations assigned to locations successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "5 stations assigned to locations successfully!"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/team-members": {
"get": {
"tags": [
"Team Members"
],
"summary": "List all team members",
"description": "Retrieve a list of all team members for the current business, optionally filtered by station or location",
"operationId": "494b15ab5daedc279810a2d1649e00e6",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-locationId",
"in": "header",
"description": "Location ID header for filtering",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "X-stationId",
"in": "header",
"description": "Station ID header for filtering",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "location",
"in": "query",
"description": "Filter team members by location IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "station",
"in": "query",
"description": "Filter team members by station IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "1,2,3"
}
},
{
"name": "roles",
"in": "query",
"description": "Filter team members by roles (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "Doctor,Nurse,Location Manager"
}
},
{
"name": "location_ids",
"in": "query",
"description": "Filter team members by location IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "79,101"
}
},
{
"name": "station_ids",
"in": "query",
"description": "Filter team members by station IDs (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "184,123"
}
},
{
"name": "role_ids",
"in": "query",
"description": "Filter team members by role names (multiple values allowed, comma-separated)",
"required": false,
"schema": {
"type": "string",
"example": "STATION_MANAGER,BUSINESS_MANAGER"
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter team members created from this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-09-01"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter team members created until this date (YYYY-MM-DD format)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-09-22"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of items per page (1-100, default: 15)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"example": 15
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort by",
"required": false,
"schema": {
"type": "string",
"enum": [
"name",
"email",
"phone_number",
"has_accepted",
"dateOnboarded"
],
"example": "name"
}
},
{
"name": "sort_order",
"in": "query",
"description": "Sort order (asc or desc)",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
}
}
],
"responses": {
"200": {
"description": "List of team members retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team members retrieved successfully"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Station A"
}
},
"type": "object"
}
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Location A"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"has_accepted": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 50
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Missing organisation header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organisation header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"User is not authenticated."
]
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - Not authorized for this business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Business not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"No business found for the given organisation ID."
]
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Team Members"
],
"summary": "Add a new team member",
"description": "Creates a new team member or adds an existing user to the team with specified roles and permissions. The user will receive an invitation email to set their password and complete registration.",
"operationId": "d215eb5a7db9b7f4ecff72917622a2b9",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"first_name",
"last_name",
"email",
"roles"
],
"properties": {
"first_name": {
"description": "First name of the team member",
"type": "string",
"example": "John"
},
"last_name": {
"description": "Last name of the team member",
"type": "string",
"example": "Doe"
},
"email": {
"description": "Email address of the team member",
"type": "string",
"format": "email",
"example": "john.doe@example.com"
},
"phone_number": {
"description": "Phone number of the team member",
"type": "string",
"example": "+1234567890"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"description": "Role type",
"type": "string",
"enum": [
"BUSINESS_MANAGER",
"LOCATION_MANAGER",
"STATION_MANAGER",
"SERVICE_PROVIDER",
"TEAM_MEMBER"
],
"example": "TEAM_MEMBER"
},
"location_ids": {
"description": "Location IDs for LOCATION_MANAGER and TEAM_MEMBER roles",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
},
"station_ids": {
"description": "Station IDs for STATION_MANAGER, SERVICE_PROVIDER and TEAM_MEMBER roles",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
"type": "object"
},
"example": [
{
"role": "TEAM_MEMBER",
"station_ids": [
1,
2
],
"location_ids": [
1
]
},
{
"role": "LOCATION_MANAGER",
"location_ids": [
1,
2
]
}
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Team member created successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/UserTeamMemberResource"
}
},
"type": "object"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Invalid role specified"
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Invalid or missing authentication token"
]
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"email": [
"The email field is required."
]
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/team-members/{id}": {
"get": {
"tags": [
"Team Members"
],
"summary": "Get a specific team member",
"description": "Retrieve details of a specific team member by ID",
"operationId": "ebb5840049725aabbad4f2a153829217",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Team member ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Team member details retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team member retrieved successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Station A"
}
},
"type": "object"
}
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Location A"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"has_accepted": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Missing organisation header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organisation header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"User is not authenticated."
]
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - Not authorized for this business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Team member not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Team member not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"The specified team member was not found."
]
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Team Members"
],
"summary": "Update a team member's roles",
"description": "Update the roles and permissions of an existing team member",
"operationId": "ef1903ac6f00911d983345733e092dfc",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Team member ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"roles"
],
"properties": {
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"description": "Role type",
"type": "string",
"enum": [
"BUSINESS_MANAGER",
"LOCATION_MANAGER",
"STATION_MANAGER",
"SERVICE_PROVIDER",
"TEAM_MEMBER"
],
"example": "TEAM_MEMBER"
},
"location_ids": {
"description": "Location IDs for LOCATION_MANAGER and TEAM_MEMBER roles",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
},
"station_ids": {
"description": "Station IDs for STATION_MANAGER, SERVICE_PROVIDER and TEAM_MEMBER roles",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
}
},
"type": "object"
},
"example": [
{
"role": "TEAM_MEMBER",
"station_ids": [
1,
2
],
"location_ids": [
1
]
},
{
"role": "LOCATION_MANAGER",
"location_ids": [
1,
2
]
}
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Team member roles updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team member roles updated successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"roles": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"stations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Station A"
}
},
"type": "object"
}
},
"locations": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Location A"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"has_accepted": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Missing organisation header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organisation header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"User is not authenticated."
]
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - Not authorized for this business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Team member not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Team member not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"The specified team member was not found."
]
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"roles": [
"The roles field is required."
]
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Team Members"
],
"summary": "Remove a team member",
"description": "Remove a team member from the business by deleting their roles (user profile remains intact)",
"operationId": "5de7711646148a5fda5bbb3b7226082a",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Team member ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Team member removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team member removed successfully"
},
"data": {
"type": "null"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Missing organisation header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organisation header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"User is not authenticated."
]
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - Not authorized for this business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Team member not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Team member not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"The specified team member was not found."
]
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/team-members/bulk-delete": {
"post": {
"tags": [
"Team Members"
],
"summary": "Bulk remove team members",
"description": "Remove multiple team members from the business by deleting their roles and business associations (user profile is deleted if they do not own any businesses).",
"operationId": "3c32aef2d90e642f22cf8565a3d74fe7",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"ids"
],
"properties": {
"ids": {
"description": "User IDs of team members to remove",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Team members removed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team members removed successfully"
},
"data": {
"properties": {
"deleted": {
"type": "integer",
"example": 3
},
"processed": {
"type": "integer",
"example": 3
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"ids": [
"The ids field is required and must be an array of integers."
]
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/team-members/resend-invitation": {
"post": {
"tags": [
"Team Members"
],
"summary": "Resend a team member invitation",
"description": "Resend an invitation email to a team member who hasn't accepted their invitation yet",
"operationId": "82603e116cd3847e1fd6cf2069eee6df",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID header required for business context",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"user_id"
],
"properties": {
"user_id": {
"description": "User ID to resend invitation to",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Invitation resent successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Invitation sent again successfully"
},
"data": {
"type": "null"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Bad request - Missing organisation header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organisation header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthenticated",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"User is not authenticated."
]
}
},
"type": "object"
}
}
}
},
"403": {
"description": "Forbidden - Not authorized for this business",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"404": {
"description": "User or invitation not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "User or invitation not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"The specified user or invitation was not found."
]
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"type": "object",
"example": {
"user_id": [
"The user_id field is required."
]
}
}
},
"type": "object"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Server error"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"An error occurred while processing the request."
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/check-uniqueness": {
"get": {
"tags": [
"Validation"
],
"summary": "Check uniqueness of a value",
"description": "Check if a value is unique for a specific feature within the organization.",
"operationId": "9e3eda6641d068ab6d6ebe42d57e0a96",
"parameters": [
{
"name": "X-organizationId",
"in": "header",
"description": "Organization ID",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "feature",
"in": "query",
"description": "The feature to check uniqueness for",
"required": true,
"schema": {
"type": "string",
"enum": [
"location",
"station",
"provider",
"service",
"category",
"intake",
"client_attribute",
"client",
"user"
],
"example": "client"
}
},
{
"name": "value",
"in": "query",
"description": "The value to check for uniqueness",
"required": true,
"schema": {
"type": "string",
"example": "John Doe"
}
},
{
"name": "column",
"in": "query",
"description": "Specific column to check against (optional, depends on feature)",
"required": false,
"schema": {
"type": "string",
"example": "email"
}
},
{
"name": "existing_id",
"in": "query",
"description": "ID of existing record to exclude from check (for updates)",
"required": false,
"schema": {
"type": "integer",
"example": 123
}
}
],
"responses": {
"200": {
"description": "Uniqueness check result",
"content": {
"application/json": {
"schema": {
"properties": {
"available": {
"description": "True if the value is unique/available, false otherwise",
"type": "boolean",
"example": true
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/profile": {
"get": {
"tags": [
"User Profile"
],
"summary": "Get authenticated user profile",
"description": "Get the authenticated user's profile",
"operationId": "5c607798812615f76b214c171e282249",
"responses": {
"200": {
"description": "User profile retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Profile retrieved successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"profile_picture": {
"type": "string",
"example": "https://yourdomain.com/storage/profile-pictures/user123.jpg",
"nullable": true
},
"intercom_user_hash": {
"type": "string",
"example": "hash_value"
},
"is_email_verified": {
"type": "boolean",
"example": true
},
"two_factor_enable": {
"type": "boolean",
"example": false
},
"business_count": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"error": {
"type": "string",
"example": "AuthenticationException"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"User Profile"
],
"summary": "Update authenticated user profile",
"description": "Update the authenticated user's profile",
"operationId": "ca3f944d1fcd650768a32e8db8105dcd",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"profile_picture": {
"description": "Profile picture URL from upload endpoint",
"type": "string",
"format": "url",
"example": "uploads/profile123.jpg"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Profile updated successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Profile updated successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"profile_picture": {
"type": "string",
"example": "https://yourdomain.com/storage/profile-pictures/user123.jpg",
"nullable": true
},
"intercom_user_hash": {
"type": "string",
"example": "hash_value"
},
"is_email_verified": {
"type": "boolean",
"example": true
},
"two_factor_enable": {
"type": "boolean",
"example": false
},
"business_count": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"first_name": {
"type": "array",
"items": {
"type": "string",
"example": "The first name field is required."
}
},
"last_name": {
"type": "array",
"items": {
"type": "string",
"example": "The last name field is required."
}
},
"profile_picture": {
"type": "array",
"items": {
"type": "string",
"example": "The profile picture must be a valid URL."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"error": {
"type": "string",
"example": "AuthenticationException"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/profile/password": {
"put": {
"tags": [
"User Profile"
],
"summary": "Change authenticated user password",
"description": "Change the authenticated user's password",
"operationId": "b83cbb7da725041eced9c66f05e13e2e",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"current_password": {
"type": "string",
"example": "oldpassword123"
},
"new_password": {
"type": "string",
"example": "newpassword123"
},
"new_password_confirmation": {
"type": "string",
"example": "newpassword123"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Password changed successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Password changed successfully"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"current_password": {
"type": "array",
"items": {
"type": "string",
"example": "The current password is incorrect."
}
},
"new_password": {
"type": "array",
"items": {
"type": "string",
"example": "The new password must be at least 8 characters."
}
},
"new_password_confirmation": {
"type": "array",
"items": {
"type": "string",
"example": "The new password confirmation does not match."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"error": {
"type": "string",
"example": "AuthenticationException"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/profile/settings/{key}": {
"get": {
"tags": [
"User Profile"
],
"summary": "Get specific user setting",
"description": "Get specific user setting",
"operationId": "6f3d97341908345c22a131e03c60387e",
"parameters": [
{
"name": "key",
"in": "path",
"description": "Setting key identifier",
"required": true,
"schema": {
"type": "string",
"example": "theme_preference"
}
}
],
"responses": {
"200": {
"description": "Setting retrieved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Setting retrieved successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "theme_preference"
},
"config": {
"type": "object",
"example": {
"theme": "dark",
"language": "en"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "Setting not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Setting not found"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"error": {
"type": "string",
"example": "AuthenticationException"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"User Profile"
],
"summary": "Save user setting",
"description": "Save user setting",
"operationId": "3208b24a823fca7218e9a8e0f31fb991",
"parameters": [
{
"name": "key",
"in": "path",
"description": "Setting key identifier",
"required": true,
"schema": {
"type": "string",
"example": "theme_preference"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"config": {
"type": "object",
"example": {
"theme": "dark",
"language": "en"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Setting saved successfully",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Setting saved successfully"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "theme_preference"
},
"config": {
"type": "object",
"example": {
"theme": "dark",
"language": "en"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Validation failed"
},
"errors": {
"properties": {
"config": {
"type": "array",
"items": {
"type": "string",
"example": "The config field is required."
}
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"error": {
"type": "string",
"example": "AuthenticationException"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"ClientImportFileDto": {
"description": "Data Transfer Object for client import file processing",
"properties": {
"businessId": {
"description": "Business ID",
"type": "integer",
"example": 1
},
"fileName": {
"description": "Name of the import file",
"type": "string",
"example": "clients_import.csv"
},
"cacheKey": {
"description": "Cache key for storing import data",
"type": "string",
"example": "import_cache_123",
"nullable": true
},
"headers": {
"description": "CSV headers",
"type": "array",
"items": {
"type": "string"
},
"example": [
"name",
"email",
"phone"
],
"nullable": true
},
"data": {
"description": "Import data rows",
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
},
"nullable": true
},
"invalidRowIds": {
"description": "Row IDs that failed validation",
"type": "array",
"items": {
"type": "integer"
},
"example": [
2,
5,
8
],
"nullable": true
},
"discardedRowIds": {
"description": "Row IDs that were discarded",
"type": "array",
"items": {
"type": "integer"
},
"example": [
3,
7
],
"nullable": true
}
},
"type": "object"
},
"SbLocationResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Office"
},
"address": {
"type": "string",
"nullable": true
},
"country": {
"type": "string",
"nullable": true
},
"state": {
"type": "string",
"nullable": true
},
"city": {
"type": "string",
"nullable": true
},
"zip_code": {
"type": "string",
"nullable": true
},
"time_zone": {
"type": "string",
"example": "Africa/Lagos",
"nullable": true
},
"email": {
"type": "string",
"example": "office@example.com",
"nullable": true
},
"phone_number": {
"type": "string",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true
},
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "string",
"nullable": true
},
"rooms_count": {
"type": "integer",
"example": 5
},
"booked_reservations_count": {
"type": "integer",
"example": 10
},
"cancelled_reservations_count": {
"type": "integer",
"example": 2
},
"amenities": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "WiFi"
},
"icon": {
"type": "string",
"example": "wifi",
"nullable": true
}
},
"type": "object"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"SbTeamMemberResource": {
"properties": {
"id": {
"type": "integer"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone_number": {
"type": "string",
"nullable": true
},
"role": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"user_id": {
"type": "integer",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"TwoFactorResponse": {
"properties": {
"token": {
"type": "string",
"example": "temp-token-abc123"
},
"expires_in": {
"type": "integer",
"example": 600
},
"two_factor_skip": {
"type": "boolean",
"example": true
},
"twoFactor": {
"type": "boolean",
"example": true
},
"two_factor_enable": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"AutomationAction": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"automation_id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Send Welcome Email"
},
"description": {
"type": "string",
"example": "Sends welcome email to new patients"
},
"action_type": {
"type": "string",
"example": "send_email"
},
"action_config": {
"type": "object"
},
"execution_order": {
"type": "integer",
"example": 1
},
"is_active": {
"type": "boolean",
"example": true
},
"operator": {
"description": "Action operator: equal, not_equal, neutral",
"type": "string",
"enum": [
"equal",
"not_equal",
"neutral"
],
"example": "neutral"
},
"conditions": {
"type": "array",
"items": {
"properties": {
"type": {
"type": "string",
"example": "patient_category"
},
"value": {
"type": "string",
"example": "new_patient"
}
},
"type": "object"
}
},
"retry_config": {
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"Automation": {
"properties": {
"uuid": {
"description": "Unique identifier for the automation",
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"name": {
"description": "Name of the automation",
"type": "string",
"example": "Welcome Email Automation"
},
"description": {
"description": "Description of the automation",
"type": "string",
"example": "Sends welcome email to new patients"
},
"trigger_type": {
"description": "Type of trigger that activates this automation",
"type": "string",
"example": "patient_validation"
},
"start_date": {
"description": "Start date when automation becomes active",
"type": "string",
"format": "date",
"example": "2023-10-27"
},
"end_date": {
"description": "End date when automation becomes inactive",
"type": "string",
"format": "date",
"example": "2024-10-27"
},
"is_active": {
"description": "Whether the automation is currently active",
"type": "boolean",
"example": true
},
"status": {
"description": "Status of the automation (0 = draft, 1 = published)",
"type": "integer",
"example": 1
},
"business_id": {
"description": "ID of the business this automation belongs to",
"type": "integer",
"example": 1
},
"settings": {
"description": "Additional settings for the automation",
"type": "object",
"example": {
"ui_config": {
"theme": "dark"
},
"display_options": {
"show_timeline": true
}
}
},
"success_count": {
"description": "Number of successful executions (2-digit random)",
"type": "integer",
"example": 45
},
"fail_count": {
"description": "Number of failed executions (2-digit random)",
"type": "integer",
"example": 12
},
"created_at": {
"description": "When the automation was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the automation was last updated",
"type": "string",
"format": "date-time"
},
"location_selections": {
"description": "List of location selections for this automation",
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationSelection"
}
}
},
"type": "object"
},
"AutomationOwner": {
"properties": {
"id": {
"description": "Unique identifier for the automation owner",
"type": "integer",
"example": 1
},
"owningable_id": {
"description": "ID of the owning entity",
"type": "integer",
"example": 1
},
"owningable_type": {
"description": "Class name of the owning entity",
"type": "string",
"example": "App\\\\Models\\\\Location"
},
"automation_id": {
"description": "ID of the automation",
"type": "integer",
"example": 1
},
"owningable": {
"description": "The owning entity (User, Location, Station, or LocationStation)",
"type": "object"
},
"created_at": {
"description": "When the owner was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the owner was last updated",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"LocationStation": {
"properties": {
"id": {
"description": "Unique identifier for the location-station relationship",
"type": "integer",
"example": 1
},
"location_id": {
"description": "ID of the location",
"type": "integer",
"example": 1
},
"station_id": {
"description": "ID of the station",
"type": "integer",
"example": 1
},
"location": {
"description": "The location entity",
"type": "object"
},
"station": {
"description": "The station entity",
"type": "object"
},
"unique_identifier": {
"description": "Unique identifier for this location-station relationship",
"type": "string",
"example": "location_1_station_1"
},
"is_active": {
"description": "Whether this location-station relationship is active",
"type": "boolean",
"example": true
},
"created_at": {
"description": "When the relationship was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the relationship was last updated",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"LocationSelection": {
"properties": {
"location_id": {
"description": "ID of the location",
"type": "integer",
"example": 1
},
"all_stations": {
"description": "Whether to include all stations in this location",
"type": "boolean",
"example": true
},
"station_ids": {
"description": "Array of station IDs to include (only used when all_stations is false)",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
"type": "object"
},
"AutomationConditionType": {
"properties": {
"uuid": {
"description": "Unique identifier for the condition type",
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174004"
},
"condition_type": {
"description": "Type identifier for the condition",
"type": "string",
"example": "field_equals"
},
"name": {
"description": "Display name for the condition type",
"type": "string",
"example": "Field Equals"
},
"description": {
"description": "Description of what this condition checks",
"type": "string",
"example": "Check if a field equals a specific value"
},
"config_schema": {
"description": "Schema defining the configuration options for this condition",
"type": "object"
},
"default_config": {
"description": "Default configuration values for this condition",
"type": "object"
},
"operators": {
"description": "Available operators for this condition",
"type": "array",
"items": {
"type": "string"
}
},
"field_options": {
"description": "Available field options for this condition",
"type": "array",
"items": {
"type": "string"
}
},
"is_active": {
"description": "Whether this condition type is active",
"type": "boolean",
"example": true
},
"is_system": {
"description": "Whether this is a system-defined condition type",
"type": "boolean",
"example": true
},
"sort_order": {
"description": "Order for displaying this condition type",
"type": "integer",
"example": 1
},
"created_at": {
"description": "When the condition type was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the condition type was last updated",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"AutomationCheckType": {
"properties": {
"uuid": {
"description": "Unique identifier for the check type",
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174005"
},
"check_type": {
"description": "Type identifier for the check",
"type": "string",
"example": "response_received"
},
"name": {
"description": "Display name for the check type",
"type": "string",
"example": "Response Received"
},
"description": {
"description": "Description of what this check does",
"type": "string",
"example": "Check if a response was received from patient"
},
"config_schema": {
"description": "Schema defining the configuration options for this check",
"type": "object"
},
"default_config": {
"description": "Default configuration values for this check",
"type": "object"
},
"check_logic": {
"description": "Logic for performing the check",
"type": "object"
},
"return_types": {
"description": "What types of values this check can return",
"type": "array",
"items": {
"type": "string"
}
},
"field_options": {
"description": "Available field options for this check",
"type": "array",
"items": {
"type": "string"
}
},
"is_active": {
"description": "Whether this check type is active",
"type": "boolean",
"example": true
},
"is_system": {
"description": "Whether this is a system-defined check type",
"type": "boolean",
"example": true
},
"sort_order": {
"description": "Order for displaying this check type",
"type": "integer",
"example": 1
},
"created_at": {
"description": "When the check type was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the check type was last updated",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"AutomationActionType": {
"properties": {
"uuid": {
"description": "Unique identifier for the action type",
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174003"
},
"action_type": {
"description": "Type identifier for the action",
"type": "string",
"example": "send_email"
},
"name": {
"description": "Display name for the action type",
"type": "string",
"example": "Send Email"
},
"description": {
"description": "Description of what this action does",
"type": "string",
"example": "Send an email notification to the patient or team member"
},
"config_schema": {
"description": "Schema defining the configuration options for this action",
"type": "object"
},
"default_config": {
"description": "Default configuration values for this action",
"type": "object"
},
"required_fields": {
"description": "Required fields for this action configuration",
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"description": "Optional fields for this action configuration",
"type": "array",
"items": {
"type": "string"
}
},
"is_active": {
"description": "Whether this action type is active",
"type": "boolean",
"example": true
},
"is_system": {
"description": "Whether this is a system-defined action type",
"type": "boolean",
"example": true
},
"sort_order": {
"description": "Order for displaying this action type",
"type": "integer",
"example": 1
},
"created_at": {
"description": "When the action type was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the action type was last updated",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"AutomationTriggerType": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"trigger_type": {
"type": "string",
"example": "patient_validation"
},
"name": {
"type": "string",
"example": "Patient Validation"
},
"description": {
"type": "string",
"example": "Triggered when a patient account is validated"
},
"config_schema": {
"type": "object"
},
"default_config": {
"type": "object"
},
"is_active": {
"type": "boolean",
"example": true
},
"is_system": {
"type": "boolean",
"example": true
},
"sort_order": {
"type": "integer",
"example": 1
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"BusinessDetails": {
"required": [
"name",
"business_category_id"
],
"properties": {
"id": {
"description": "Organization Id",
"type": "string",
"example": "1"
},
"name": {
"description": "Organization name",
"type": "string",
"example": "Acme Medical Clinic"
},
"address": {
"description": "Street address",
"type": "string",
"example": "123 Main Street",
"nullable": true
},
"country": {
"description": "Country name",
"type": "string",
"example": "United States",
"nullable": true
},
"state": {
"description": "State or province",
"type": "string",
"example": "California",
"nullable": true
},
"city": {
"description": "City name",
"type": "string",
"example": "San Francisco",
"nullable": true
},
"zip_code": {
"description": "Postal/ZIP code",
"type": "string",
"example": "94102",
"nullable": true
},
"phone_number": {
"description": "Organization phone number",
"type": "string",
"example": "+1-555-123-4567",
"nullable": true
},
"email": {
"description": "Organization email address (optional - defaults to user's email if not provided)",
"type": "string",
"format": "email",
"example": "contact@acmemedical.com"
},
"business_category_id": {
"description": "ID from business_categories table",
"type": "integer",
"example": 1
},
"logo_url": {
"description": "Logo URL or base64 string",
"type": "string",
"example": "https://example.com/logo.png"
},
"sso_enable": {
"description": "Whether SSO is enabled for this organization",
"type": "boolean",
"example": true
},
"sso_login": {
"description": "SSO login URL for users",
"type": "string",
"example": "https://example.com/saml/login/user"
},
"sso_login_client": {
"description": "SSO login URL for clients",
"type": "string",
"example": "https://example.com/saml/login/client"
},
"locations_count": {
"description": "Total number of locations associated with the business",
"type": "integer",
"example": 5
},
"stations_count": {
"description": "Total number of stations associated with the business",
"type": "integer",
"example": 12
},
"services_count": {
"description": "Total number of services associated with the business",
"type": "integer",
"example": 34
}
},
"type": "object"
},
"WorkingHours": {
"properties": {
"day": {
"description": "Day of the week",
"type": "string",
"example": "monday"
},
"start_time": {
"description": "Opening time",
"type": "string",
"example": "09:00"
},
"end_time": {
"description": "Closing time",
"type": "string",
"example": "17:00"
},
"is_open": {
"description": "Whether open on this day",
"type": "boolean",
"example": true
}
},
"type": "object"
},
"QueueSettings": {
"properties": {
"time_zone": {
"description": "Business timezone",
"type": "string",
"example": "America/Los_Angeles"
},
"schedule_block_in_minute": {
"description": "Appointment slot duration in minutes",
"type": "integer",
"example": 30
},
"manual_wait_time": {
"description": "Estimated wait time in minutes",
"type": "integer",
"example": 15
}
},
"type": "object"
},
"ChatMessage": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"station_id": {
"type": "integer",
"example": 123
},
"client_id": {
"type": "integer",
"example": 456
},
"sender_id": {
"description": "ID of the actual sender (station ID for station messages, client ID for client messages)",
"type": "integer",
"example": 123
},
"sender_type": {
"description": "Type of sender: 'station' for user messages, 'client' for client messages",
"type": "string",
"enum": [
"station",
"client"
],
"example": "station"
},
"message": {
"type": "string",
"example": "Hello! How can I help you today?"
},
"message_type": {
"type": "string",
"enum": [
"text",
"file",
"image",
"audio",
"video"
],
"example": "text"
},
"is_read": {
"type": "boolean",
"example": false
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:00:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:00:00Z"
},
"senderStation": {
"description": "Station who sent the message (for station messages)",
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "Medical Center"
},
"image": {
"type": "string",
"example": "https://example.com/station-image.jpg"
}
},
"type": "object",
"nullable": true
},
"sender_client": {
"description": "Client who sent the message (for client messages)",
"properties": {
"id": {
"type": "integer",
"example": 456
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Smith"
}
},
"type": "object",
"nullable": true
},
"station": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "Medical Center"
},
"image": {
"type": "string",
"example": "https://example.com/station-image.jpg"
}
},
"type": "object"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 456
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Smith"
}
},
"type": "object"
}
},
"type": "object"
},
"Conversation": {
"properties": {
"type": {
"description": "Type of conversation: 'station' for station conversations, 'client' for client conversations",
"type": "string",
"example": "station"
},
"other_user_id": {
"description": "ID of the other participant (client ID for station conversations, station ID for client conversations)",
"type": "integer",
"example": 456
},
"other_user": {
"description": "Other participant in the conversation",
"properties": {
"id": {
"type": "integer",
"example": 456
},
"first_name": {
"type": "string",
"example": "Jane"
},
"last_name": {
"type": "string",
"example": "Smith"
}
},
"type": "object"
},
"last_message": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"message": {
"type": "string",
"example": "Hello! How can I help you today?"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:00:00Z"
}
},
"type": "object"
},
"unread_count": {
"description": "Number of unread messages (client messages for station view, non-client messages for client view)",
"type": "integer",
"example": 0
},
"total_messages": {
"description": "Total number of messages in the conversation",
"type": "integer",
"example": 1
}
},
"type": "object"
},
"ClientUserLoginResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Welcome back"
},
"data": {
"properties": {
"token": {
"type": "string",
"example": "jwt-token-xyz789"
},
"expires_in": {
"type": "integer",
"example": 3600
},
"token_type": {
"type": "string",
"example": "bearer"
},
"user": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"email_verified_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"client_profiles": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"user_id": {
"type": "integer",
"example": 1
},
"client_id": {
"type": "integer",
"example": 1
},
"business_id": {
"type": "integer",
"example": 1
},
"is_active": {
"type": "boolean",
"example": true
},
"business": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Medical"
}
},
"type": "object"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
},
"ClientRegistrationRequest": {
"required": [
"email",
"password",
"password_confirmation",
"first_name",
"last_name"
],
"properties": {
"email": {
"description": "Unique email address",
"type": "string",
"format": "email",
"example": "john@example.com"
},
"password": {
"description": "Password (minimum 8 characters)",
"type": "string",
"format": "password",
"minLength": 8,
"example": "SecurePass123!"
},
"password_confirmation": {
"description": "Password confirmation",
"type": "string",
"format": "password",
"example": "SecurePass123!"
},
"first_name": {
"description": "User's first name",
"type": "string",
"maxLength": 255,
"example": "John"
},
"last_name": {
"description": "User's last name",
"type": "string",
"maxLength": 255,
"example": "Doe"
},
"phone_number": {
"description": "User's phone number (optional)",
"type": "string",
"maxLength": 20,
"example": "+1234567890",
"nullable": true
},
"client_id": {
"description": "Existing patient ID to connect (optional)",
"type": "integer",
"example": 1,
"nullable": true
}
},
"type": "object"
},
"ClientLoginRequest": {
"required": [
"email",
"password"
],
"properties": {
"email": {
"description": "User's email address",
"type": "string",
"format": "email",
"example": "john@example.com"
},
"password": {
"description": "User's password",
"type": "string",
"format": "password",
"example": "SecurePass123!"
}
},
"type": "object"
},
"ClientVerificationRequest": {
"required": [
"token"
],
"properties": {
"token": {
"description": "Email verification token",
"type": "string",
"example": "verification-token-abc123"
}
},
"type": "object"
},
"BookingCompletedRequest": {
"description": "Request payload for completing a booking",
"required": [
"appointment_id",
"appointment_date"
],
"properties": {
"appointment_id": {
"description": "Unique identifier for the appointment from the schedule service",
"type": "string",
"example": "appointment_12345"
},
"appointment_date": {
"description": "Date and time of the appointment",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"status": {
"description": "Booking status - defaults to auto-approve logic if not provided",
"type": "string",
"enum": [
"pending",
"confirmed"
],
"example": "confirmed"
}
},
"type": "object"
},
"SlotBookedRequest": {
"required": [
"location_id",
"station_id",
"service_id"
],
"properties": {
"location_id": {
"description": "ID of the selected location",
"type": "integer",
"example": 1
},
"station_id": {
"description": "ID of the selected station",
"type": "integer",
"example": 2
},
"service_id": {
"description": "ID of the selected service",
"type": "integer",
"example": 3
}
},
"type": "object"
},
"SlotBookedResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Slot booked successfully"
},
"data": {
"properties": {
"forms": {
"properties": {
"has_form": {
"type": "boolean",
"example": true
},
"form": {
"$ref": "#/components/schemas/FormDetail"
}
},
"type": "object"
},
"intakes": {
"properties": {
"has_intakes": {
"type": "boolean",
"example": true
},
"intakes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomIntakeDetail"
}
}
},
"type": "object"
},
"session": {
"properties": {
"is_slot_booked": {
"type": "boolean",
"example": true
},
"booked_service_id": {
"type": "integer",
"example": 3
},
"appointment_method_id": {
"type": "integer",
"example": 1
},
"booked_location_id": {
"type": "integer",
"example": 1
},
"booked_station_id": {
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"FormDetail": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Patient Registration Form"
},
"description": {
"type": "string",
"example": "Complete your patient registration information"
},
"sections": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Personal Information"
},
"order": {
"type": "integer",
"example": 1
},
"fields": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "full_name"
},
"type": {
"type": "string",
"example": "text"
},
"required": {
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"value": {
"type": "string",
"example": "option1"
},
"label": {
"type": "string",
"example": "Option 1"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"CustomIntakeDetail": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "emergency_contact"
},
"name": {
"type": "string",
"example": "Emergency Contact"
},
"subtitle": {
"type": "string",
"example": "Who to contact in case of emergency",
"nullable": true
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
],
"example": "text"
},
"field_requirement": {
"type": "string",
"enum": [
"no",
"yes",
"conditional"
],
"example": "yes"
},
"allow_multiple": {
"type": "boolean",
"example": false
},
"long_text": {
"type": "boolean",
"example": false
},
"numeric_unit_title": {
"type": "string",
"example": "kg",
"nullable": true
},
"info_text_value": {
"type": "string",
"example": "Additional information",
"nullable": true
},
"approved_formats": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"pdf",
"jpg"
],
"nullable": true
},
"image": {
"type": "string",
"example": "path/to/image.jpg",
"nullable": true
},
"order": {
"type": "integer",
"example": 1
},
"is_visible": {
"type": "boolean",
"example": true
},
"default_value": {
"description": "Pre-filled value from previous client responses",
"type": "string",
"example": "John Doe",
"nullable": true
},
"options": {
"description": "Available options for dropdown/radio/checkbox fields",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"value": {
"type": "string",
"example": "option1"
},
"label": {
"type": "string",
"example": "Option 1"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
},
"CustomIntakesSaveRequest": {
"required": [
"intakes"
],
"properties": {
"intakes": {
"type": "array",
"items": {
"required": [
"intake_id",
"responses"
],
"properties": {
"intake_id": {
"description": "ID of the custom intake form",
"type": "integer",
"example": 1
},
"responses": {
"description": "Key-value pairs of field responses",
"properties": {
"allergies": {
"type": "string",
"example": "Penicillin"
},
"emergency_contact": {
"type": "string",
"example": "Jane Doe"
},
"emergency_phone": {
"type": "string",
"example": "+1-555-111-2222"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
},
"CustomIntakesSaveResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Custom intakes saved successfully"
},
"data": {
"properties": {
"saved_count": {
"description": "Number of intakes successfully saved",
"type": "integer",
"example": 2
}
},
"type": "object"
}
},
"type": "object"
},
"PublicFormSubmitRequest": {
"required": [
"form_id",
"responses"
],
"properties": {
"form_id": {
"description": "UUID of the form to submit",
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"responses": {
"type": "array",
"items": {
"required": [
"field_id",
"value"
],
"properties": {
"field_id": {
"description": "UUID of the form field",
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"value": {
"description": "Value of the field response"
}
},
"type": "object"
}
}
},
"type": "object"
},
"FormSubmitResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Form response created successfully"
},
"data": {
"$ref": "#/components/schemas/PublicFormResponseResource"
}
},
"type": "object"
},
"PublicFormResponseResource": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440002"
},
"form_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"customer_id": {
"type": "integer",
"example": 123
},
"location_id": {
"type": "integer",
"example": 1
},
"station_id": {
"type": "integer",
"example": 2
},
"responses": {
"type": "array",
"items": {
"properties": {
"field_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"value": {
"description": "Submitted field value"
}
},
"type": "object"
}
},
"submitted_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"BookingCompletedResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking completed successfully"
},
"data": {
"properties": {
"message": {
"type": "string",
"example": "Booking completed successfully"
}
},
"type": "object"
}
},
"type": "object"
},
"ScheduleValidationErrorResponse": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"description": "Field-specific validation errors or business logic errors",
"properties": {
"location_id": {
"type": "array",
"items": {
"type": "string",
"example": "The location id field is required."
}
},
"station_id": {
"type": "array",
"items": {
"type": "string",
"example": "The station id field is required."
}
},
"service_id": {
"type": "array",
"items": {
"type": "string",
"example": "The service id field is required."
}
},
"appointment_method_id": {
"type": "array",
"items": {
"type": "string",
"example": "The appointment method id field is required."
}
},
"form_id": {
"type": "array",
"items": {
"type": "string",
"example": "The form id field is required."
}
},
"responses": {
"type": "array",
"items": {
"type": "string",
"example": "The responses field is required."
}
},
"intakes": {
"type": "array",
"items": {
"type": "string",
"example": "The intakes field is required."
}
},
"business_logic": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid location, station, or service for this business"
}
},
"session_validation": {
"type": "array",
"items": {
"type": "string",
"example": "Missing location, station or service information from booking session"
}
},
"form_mismatch": {
"type": "array",
"items": {
"type": "string",
"example": "Form ID mismatch - the form ID in the request does not match the form for this location/station/service"
}
},
"incomplete_requirements": {
"type": "array",
"items": {
"type": "string",
"example": "Form submission required"
}
}
},
"type": "object"
}
},
"type": "object"
},
"ScheduleInfoForDomainResponse": {
"properties": {
"success": {
"description": "Client API Public Booking Controller\n\nHandles public scheduling-related endpoints for client-facing API including\ndomain resolution, schedule data retrieval, client validation, and resource fetching.",
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Domain resolved successfully"
},
"business_id": {
"description": "ID of the resolved business",
"type": "integer",
"example": 1
},
"business_name": {
"type": "string",
"example": "Acme Medical Center"
},
"domain": {
"type": "string",
"example": "acme.medcenter.com"
},
"is_active": {
"description": "Whether the business is active",
"type": "boolean",
"example": true
}
},
"type": "object"
},
"ScheduleInfoForPathResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Schedule resolved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"business_data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Acme Medical Center"
},
"domain": {
"type": "string",
"example": "acme.medcenter.com"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"schedule_code": {
"description": "The resolved schedule link custom path",
"type": "string",
"example": "appointment-123"
},
"owner_type": {
"description": "Type of the schedule owner",
"type": "string",
"example": "business"
},
"owner_id": {
"description": "ID of the schedule owner",
"type": "integer",
"example": 1
},
"schedule_code_override": {
"description": "Flag indicating if schedule_code parameter was used to override session value",
"type": "boolean",
"example": true
},
"display_settings": {
"properties": {
"theme": {
"type": "string",
"example": "medical"
},
"primary_color": {
"type": "string",
"example": "#007bff"
},
"logo": {
"type": "string",
"example": "https://example.com/logo.png"
}
},
"type": "object"
},
"banners": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Welcome"
},
"message": {
"type": "string",
"example": "Welcome to our booking system"
},
"type": {
"type": "string",
"example": "info"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"locations": {
"description": "Available locations for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetailForScheduling"
}
},
"stations": {
"description": "Available stations/providers for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetailForScheduling"
}
},
"services": {
"description": "Available services for booking",
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetailForScheduling"
}
},
"client": {
"description": "Resolved client information",
"properties": {
"id": {
"type": "integer",
"example": 123
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"first_name": {
"type": "string",
"example": "John"
},
"last_name": {
"type": "string",
"example": "Doe"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/avatar.jpg",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"execution_data": {
"description": "Automation execution data if any automations were triggered",
"type": "object",
"nullable": true
}
},
"type": "object"
},
"LocationDetailForScheduling": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Clinic"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"zip_code": {
"type": "string",
"example": "10001"
},
"phone": {
"type": "string",
"example": "+1-555-123-4567"
},
"is_active": {
"type": "boolean",
"example": true
},
"timezone": {
"type": "string",
"example": "America/New_York"
}
},
"type": "object"
},
"StationDetailForScheduling": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Dr. John Smith"
},
"title": {
"type": "string",
"example": "General Practitioner"
},
"email": {
"type": "string",
"example": "dr.smith@clinic.com"
},
"phone": {
"type": "string",
"example": "+1-555-123-4567"
},
"is_active": {
"type": "boolean",
"example": true
},
"location_id": {
"type": "integer",
"example": 1
},
"specialties": {
"type": "array",
"items": {
"type": "string",
"example": "General Medicine"
}
}
},
"type": "object"
},
"ServiceDetailForScheduling": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "General Consultation"
},
"description": {
"type": "string",
"example": "30-minute general health consultation"
},
"duration": {
"description": "Duration in minutes",
"type": "integer",
"example": 30
},
"price": {
"type": "number",
"format": "float",
"example": 150
},
"is_active": {
"type": "boolean",
"example": true
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "In-Person"
},
"type": {
"type": "string",
"example": "in_person"
}
},
"type": "object"
}
}
},
"type": "object"
},
"ProtectedClientBookingErrorResponse": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"description": "Field-specific validation errors or business logic errors",
"properties": {
"domain": {
"type": "array",
"items": {
"type": "string",
"example": "Domain not found"
}
},
"schedule_code": {
"type": "array",
"items": {
"type": "string",
"example": "Schedule link not found"
}
},
"through": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid through parameter"
}
},
"type": {
"type": "array",
"items": {
"type": "string",
"example": "The type field is required"
}
},
"value": {
"type": "array",
"items": {
"type": "string",
"example": "The value field is required"
}
},
"location_id": {
"type": "array",
"items": {
"type": "string",
"example": "Location is required for station"
}
},
"service_id": {
"type": "array",
"items": {
"type": "string",
"example": "The service id must be an integer"
}
},
"client_validation": {
"type": "array",
"items": {
"type": "string",
"example": "Patient not allowed"
}
},
"session_validation": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid or expired booking session"
}
},
"business_logic": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid location, station, or service for this business"
}
}
},
"type": "object"
}
},
"type": "object"
},
"DomainResolveResponse": {
"properties": {
"success": {
"description": "Client API Public Booking Controller\n\nHandles public scheduling-related endpoints for client-facing API including\ndomain resolution, schedule data retrieval, client validation, and resource fetching.",
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Domain resolved successfully"
},
"business_id": {
"description": "ID of the resolved business",
"type": "integer",
"example": 1
},
"business_name": {
"type": "string",
"example": "Acme Medical Center"
},
"domain": {
"type": "string",
"example": "acme.medcenter.com"
},
"is_active": {
"description": "Whether the business is active",
"type": "boolean",
"example": true
}
},
"type": "object"
},
"ScheduleDataResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Schedule data retrieved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"properties": {
"schedule_code": {
"type": "string",
"example": "appointment-123"
},
"organization_id": {
"type": "integer",
"example": 1
},
"schedule_info": {
"properties": {
"title": {
"type": "string",
"example": "Book Your Appointment"
},
"description": {
"type": "string",
"example": "Schedule your medical appointment"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"display_settings": {
"properties": {
"theme": {
"type": "string",
"example": "medical"
},
"primary_color": {
"type": "string",
"example": "#007bff"
},
"logo": {
"type": "string",
"example": "https://example.com/logo.png"
}
},
"type": "object"
},
"security_options": {
"properties": {
"requires_verification": {
"type": "boolean",
"example": true
},
"verification_methods": {
"type": "array",
"items": {
"type": "string",
"example": "email"
}
}
},
"type": "object"
},
"verified_client_info": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
}
},
"type": "object",
"nullable": true
},
"verification_settings": {
"properties": {
"question": {
"type": "string",
"example": "What is your date of birth?"
},
"redirect_url": {
"type": "string",
"example": "https://example.com/verify"
},
"redirect_answer_value": {
"type": "string",
"example": "yes"
}
},
"type": "object",
"nullable": true
},
"banners": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Welcome"
},
"message": {
"type": "string",
"example": "Welcome to our booking system"
},
"type": {
"type": "string",
"example": "info"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"client_validation_data": {
"properties": {
"locations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"stations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetail"
}
},
"services": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetail"
}
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
},
"ClientValidationRequest": {
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Validation method type",
"type": "string",
"enum": [
"email",
"phone",
"client_id"
],
"example": "email"
},
"value": {
"description": "Value to validate (email, phone, or client ID)",
"type": "string",
"example": "john@example.com"
},
"verification_answer": {
"description": "Answer to verification question if required",
"type": "string",
"example": "1990-01-01",
"nullable": true
}
},
"type": "object"
},
"ClientValidationResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Client validated successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"properties": {
"client": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"type": "string",
"example": "+1-555-123-4567"
}
},
"type": "object"
},
"execution_data": {
"description": "Automation execution results that may restrict available options",
"properties": {
"locations": {
"description": "Restricted locations from automation",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Clinic"
}
},
"type": "object"
}
},
"services": {
"description": "Restricted services from automation",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "General Consultation"
}
},
"type": "object"
}
},
"stations": {
"description": "Restricted stations from automation",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Dr. Smith"
}
},
"type": "object"
}
}
},
"type": "object",
"nullable": true
},
"locations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"stations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetail"
}
},
"services": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetail"
}
}
},
"type": "object"
}
},
"type": "object"
},
"LocationDetail": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Clinic"
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "New York"
},
"state": {
"type": "string",
"example": "NY"
},
"zip_code": {
"type": "string",
"example": "10001"
},
"phone": {
"type": "string",
"example": "+1-555-123-4567"
},
"is_active": {
"type": "boolean",
"example": true
},
"timezone": {
"type": "string",
"example": "America/New_York"
}
},
"type": "object"
},
"StationDetail": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Dr. John Smith"
},
"title": {
"type": "string",
"example": "General Practitioner"
},
"email": {
"type": "string",
"example": "dr.smith@clinic.com"
},
"phone": {
"type": "string",
"example": "+1-555-123-4567"
},
"is_active": {
"type": "boolean",
"example": true
},
"location_id": {
"type": "integer",
"example": 1
},
"specialties": {
"type": "array",
"items": {
"type": "string",
"example": "General Medicine"
}
}
},
"type": "object"
},
"ServiceDetail": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "General Consultation"
},
"description": {
"type": "string",
"example": "30-minute general health consultation"
},
"duration": {
"description": "Duration in minutes",
"type": "integer",
"example": 30
},
"price": {
"type": "number",
"format": "float",
"example": 150
},
"is_active": {
"type": "boolean",
"example": true
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "In-Person"
},
"type": {
"type": "string",
"example": "in_person"
}
},
"type": "object"
}
}
},
"type": "object"
},
"PublicBookingErrorResponse": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"description": "Field-specific validation errors or business logic errors",
"properties": {
"domain": {
"type": "array",
"items": {
"type": "string",
"example": "Domain not found"
}
},
"schedule_code": {
"type": "array",
"items": {
"type": "string",
"example": "Schedule link not found"
}
},
"through": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid through parameter"
}
},
"type": {
"type": "array",
"items": {
"type": "string",
"example": "The type field is required"
}
},
"value": {
"type": "array",
"items": {
"type": "string",
"example": "The value field is required"
}
},
"location_id": {
"type": "array",
"items": {
"type": "string",
"example": "Location is required for station"
}
},
"service_id": {
"type": "array",
"items": {
"type": "string",
"example": "The service id must be an integer"
}
},
"client_validation": {
"type": "array",
"items": {
"type": "string",
"example": "Patient not allowed"
}
},
"session_validation": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid or expired booking session"
}
},
"business_logic": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid location, station, or service for this business"
}
}
},
"type": "object"
}
},
"type": "object"
},
"BookingInfoResponse": {
"properties": {
"success": {
"description": "Client API Public Booking Info Controller\n\nHandles public booking information endpoints for client-facing API including\nbooking link resolution, location/provider/service retrieval, and booking flow management.",
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking link resolved successfully"
},
"session_id": {
"description": "Booking session identifier",
"type": "string",
"example": "abc123def456"
},
"data": {
"properties": {
"session_id": {
"type": "string",
"example": "abc123def456"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"full_name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
}
},
"type": "object"
},
"business_data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Medical Center"
},
"domain": {
"type": "string",
"example": "medical.example.com"
}
},
"type": "object"
},
"entity": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Location"
},
"description": {
"type": "string",
"example": "Primary medical facility"
},
"booking_type": {
"type": "string",
"example": "WALK_IN"
},
"owner_type": {
"type": "string",
"example": "Location"
},
"owner_id": {
"type": "integer",
"example": 1
},
"type": {
"type": "string",
"example": "Location"
},
"image": {
"type": "string",
"example": "https://example.com/logo.png"
},
"banners": {
"type": "array",
"items": {
"type": "object"
}
},
"address": {
"type": "string",
"example": "123 Main St"
},
"city": {
"type": "string",
"example": "New York"
},
"country": {
"type": "string",
"example": "USA"
},
"phone_number": {
"type": "string",
"example": "+1-555-123-4567"
},
"domain": {
"type": "string",
"example": "medical.example.com"
},
"location_station_id": {
"type": "integer",
"nullable": true
},
"station_id": {
"type": "integer",
"nullable": true
},
"location_id": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"schedule_code": {
"type": "string",
"example": "booking-path-123"
},
"locations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationDetail"
}
},
"stations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StationDetail"
}
},
"services": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceDetail"
}
}
},
"type": "object"
}
},
"type": "object"
},
"BookingSlotResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Slot booked successfully"
},
"data": {
"properties": {
"forms": {
"properties": {
"has_form": {
"type": "boolean",
"example": true
},
"form": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"intakes": {
"properties": {
"has_intakes": {
"type": "boolean",
"example": true
},
"intakes": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"WalkInJoinInfoResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Walk-in join information retrieved"
},
"data": {
"properties": {
"position": {
"type": "integer",
"example": 3,
"nullable": true
},
"estimated_wait_time_in_minutes": {
"type": "integer",
"example": 45,
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
},
"BookSlotRequest": {
"required": [
"service_id",
"appointment_method_id"
],
"properties": {
"service_id": {
"type": "integer",
"example": 1
},
"location_station_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"station_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"location_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"appointment_method_id": {
"type": "integer",
"example": 1
},
"booking_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"slot_id": {
"type": "string",
"example": "slot_123",
"nullable": true
}
},
"type": "object"
},
"SubmitIntakeRequest": {
"required": [
"intakes"
],
"properties": {
"intakes": {
"type": "array",
"items": {
"required": [
"intake_id",
"value"
],
"properties": {
"intake_id": {
"type": "integer",
"example": 1
},
"value": {
"type": "string",
"example": "Some intake value"
}
},
"type": "object"
}
}
},
"type": "object"
},
"SubmitFormRequest": {
"required": [
"form_id",
"responses"
],
"properties": {
"form_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"responses": {
"type": "array",
"items": {
"required": [
"field_id",
"value"
],
"properties": {
"field_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"value": {
"type": "string",
"example": "Form response value"
}
},
"type": "object"
}
}
},
"type": "object"
},
"CompleteBookingRequest": {
"properties": {
"booking_id": {
"type": "string",
"example": "booking_123",
"nullable": true
}
},
"type": "object"
},
"PublicBookingInfoErrorResponse": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error": {
"type": "string",
"example": "validation_failed"
},
"errors": {
"properties": {
"path": {
"type": "array",
"items": {
"type": "string",
"example": "Booking link not found"
}
},
"service_id": {
"type": "array",
"items": {
"type": "string",
"example": "The service id is required"
}
},
"location_id": {
"type": "array",
"items": {
"type": "string",
"example": "Location is required"
}
},
"appointment_method_id": {
"type": "array",
"items": {
"type": "string",
"example": "Invalid appointment method"
}
},
"form_id": {
"type": "array",
"items": {
"type": "string",
"example": "Form ID mismatch"
}
},
"intakes": {
"type": "array",
"items": {
"type": "string",
"example": "Intakes are required"
}
}
},
"type": "object"
}
},
"type": "object"
},
"FeedbackForm": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"uuid": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"business_id": {
"type": "integer",
"example": 101
},
"client_id": {
"type": "integer",
"example": 201
},
"location_id": {
"type": "integer",
"example": 301
},
"station_id": {
"type": "integer",
"example": 401
},
"service_id": {
"type": "integer",
"example": 501
},
"booking_id": {
"type": "string",
"example": "booking_12345"
},
"booking_type": {
"type": "string",
"enum": [
"schedule",
"waitlist"
],
"example": "schedule"
},
"is_submitted": {
"type": "boolean",
"example": false
},
"rating": {
"type": "number",
"format": "float",
"example": 4.5,
"nullable": true
},
"general_feedback": {
"type": "string",
"example": "Great service experience",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T00:00:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T00:00:00Z"
},
"forms": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"uuid": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"title": {
"type": "string",
"example": "Patient Feedback Form"
},
"sections": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Service Quality"
},
"fields": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "service_rating"
},
"label": {
"type": "string",
"example": "How would you rate our service?"
},
"value": {
"type": "string",
"example": "How would "
},
"type": {
"type": "string",
"example": "rating"
},
"required": {
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"FeedbackFormResponse": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"uuid": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"business_id": {
"type": "integer",
"example": 101
},
"client_id": {
"type": "integer",
"example": 201
},
"location_id": {
"type": "integer",
"example": 301
},
"station_id": {
"type": "integer",
"example": 401
},
"service_id": {
"type": "integer",
"example": 501
},
"booking_id": {
"type": "string",
"example": "booking_12345"
},
"booking_type": {
"type": "string",
"enum": [
"schedule",
"waitlist"
],
"example": "schedule"
},
"is_submitted": {
"type": "boolean",
"example": false
},
"rating": {
"type": "number",
"format": "float",
"example": 4.5,
"nullable": true
},
"general_feedback": {
"type": "string",
"example": "Great service experience",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T00:00:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-01T00:00:00Z"
},
"forms": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"uuid": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"title": {
"type": "string",
"example": "Patient Feedback Form"
},
"sections": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Service Quality"
},
"fields": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"example": "service_rating"
},
"label": {
"type": "string",
"example": "How would you rate our service?"
},
"value": {
"type": "string",
"example": "How would "
},
"type": {
"type": "string",
"example": "rating"
},
"required": {
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"SendFeedbackFormRequest": {
"required": [
"business_id",
"service_id",
"station_id",
"location_id",
"client_id",
"booking_id"
],
"properties": {
"business_id": {
"description": "Business ID",
"type": "integer",
"example": 101
},
"service_id": {
"description": "Service ID",
"type": "integer",
"example": 501
},
"station_id": {
"description": "Station ID",
"type": "integer",
"example": 401
},
"location_id": {
"description": "Location ID",
"type": "integer",
"example": 301
},
"client_id": {
"description": "Client ID",
"type": "integer",
"example": 201
},
"booking_id": {
"description": "Booking identifier",
"type": "string",
"example": "booking_12345"
},
"booking_type": {
"description": "Type of booking",
"type": "string",
"enum": [
"schedule",
"waitlist"
],
"example": "schedule",
"nullable": true
}
},
"type": "object"
},
"SubmitFeedbackFormRequest": {
"required": [
"responses"
],
"properties": {
"rating": {
"description": "Overall rating (0-5)",
"type": "number",
"format": "float",
"example": 4.5,
"nullable": true
},
"general_feedback": {
"description": "General feedback text",
"type": "string",
"example": "Great service experience",
"nullable": true
},
"responses": {
"description": "Array of form field responses",
"type": "array",
"items": {
"required": [
"field_id",
"value"
],
"properties": {
"field_id": {
"description": "Field UUID",
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"value": {
"description": "Field response value",
"type": "string",
"example": "Excellent"
}
},
"type": "object"
}
}
},
"type": "object"
},
"FeedbackFormCreatedResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback form created successfully"
},
"data": {
"$ref": "#/components/schemas/FeedbackFormResponse"
}
},
"type": "object"
},
"FeedbackFormRetrievedResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback form retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/FeedbackFormResponse"
}
},
"type": "object"
},
"FeedbackFormSubmittedResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Feedback form submitted successfully"
},
"data": {
"$ref": "#/components/schemas/FeedbackFormResponse"
}
},
"type": "object"
},
"ProviderClientChatMessage": {
"required": [
"sender_name",
"delivery_status",
"date",
"time",
"direction",
"message"
],
"properties": {
"sender_name": {
"description": "Name of the message sender",
"type": "string",
"example": "Jane Doe"
},
"profile_picture": {
"description": "Profile picture URL of the sender",
"type": "string",
"example": "https://example.com/profile.jpg",
"nullable": true
},
"delivery_status": {
"description": "Message delivery status",
"type": "string",
"enum": [
"sent",
"failed",
"delivered",
"seen"
],
"example": "delivered"
},
"date": {
"description": "Date of the message",
"type": "string",
"example": "2024-01-08"
},
"time": {
"description": "Time of the message",
"type": "string",
"example": "14:30"
},
"direction": {
"description": "Message direction relative to provider",
"type": "string",
"enum": [
"incoming",
"outgoing"
],
"example": "incoming"
},
"message": {
"description": "Message content",
"type": "string",
"example": "Thank you for your help!"
}
},
"type": "object"
},
"ReferralServiceUpsertRequest": {
"properties": {
"name": {
"type": "string",
"example": "General Consultation"
},
"description": {
"type": "string",
"example": "Initial consultation",
"nullable": true
},
"existing_service_id": {
"type": "integer",
"example": 12,
"nullable": true
},
"is_available": {
"type": "boolean",
"example": true
},
"auto_approve": {
"type": "boolean",
"example": false
},
"is_visible": {
"type": "boolean",
"example": true
},
"time_in_minute": {
"type": "integer",
"example": 30
},
"referral_type": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"both"
],
"example": "incoming"
},
"appointment_methods": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2
]
},
"incoming_partner_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
3,
4
]
},
"outgoing_partner_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
5
]
}
},
"type": "object"
},
"RolePermission": {
"properties": {
"id": {
"description": "Role permission ID",
"type": "integer",
"example": 1
},
"role": {
"description": "Role name",
"type": "string",
"example": "BUSINESS_ADMIN"
},
"actions": {
"description": "Permission actions",
"type": "object",
"example": [
"create",
"read",
"update",
"delete"
]
},
"sidebar": {
"description": "Sidebar permissions",
"type": "object",
"example": [
"dashboard",
"users",
"settings"
]
}
},
"type": "object"
},
"TeamMemberPermissionPayload": {
"properties": {
"permission": {
"type": "string",
"example": "referral:view"
},
"module": {
"type": "string",
"example": "referral"
},
"location_ids": {
"type": "array",
"items": {
"type": "integer"
},
"nullable": true
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
},
"nullable": true
}
},
"type": "object"
},
"TeamMemberWritePermissionPayload": {
"required": [
"permission"
],
"properties": {
"permission": {
"type": "string",
"example": "referral:view"
},
"location_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
79,
101
],
"nullable": true
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
184,
123
],
"nullable": true
},
"scope": {
"description": "Omit both location_ids and station_ids to save this permission with global scope (`scope_mode = all`)",
"type": "string",
"readOnly": true,
"example": "all",
"nullable": true
}
},
"type": "object"
},
"TeamMemberScopedWritePermissionPayload": {
"required": [
"permission"
],
"properties": {
"permission": {
"type": "string",
"example": "referral:view"
}
},
"type": "object"
},
"TeamMemberDetailPayload": {
"properties": {
"id": {
"type": "integer",
"example": 15
},
"user_id": {
"type": "integer",
"example": 123,
"nullable": true
},
"first_name": {
"type": "string",
"example": "Miki"
},
"last_name": {
"type": "string",
"example": "Birhanu"
},
"email": {
"type": "string",
"format": "email",
"example": "member@example.com"
},
"phone_number": {
"type": "string",
"example": "+251900000000",
"nullable": true
},
"role_id": {
"type": "integer",
"example": 2,
"nullable": true
},
"status": {
"type": "string",
"example": "pending"
},
"permissions": {
"description": "Matches the main create/update payload. If both location_ids and station_ids are omitted, this permission has global scope.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberWritePermissionPayload"
}
},
"invitation_status": {
"type": "string",
"example": "pending",
"nullable": true
},
"is_pending_invitation": {
"type": "boolean",
"example": true
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"TeamMemberPayload": {
"properties": {
"id": {
"type": "integer"
},
"user_id": {
"type": "integer",
"nullable": true
},
"role": {
"type": "string"
},
"status": {
"type": "string"
},
"invitation_status": {
"type": "string",
"example": "pending",
"nullable": true
},
"is_pending_invitation": {
"type": "boolean",
"example": true
},
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberPermissionPayload"
}
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone_number": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"TeamMemberStoreRequest": {
"required": [
"permissions"
],
"properties": {
"user_id": {
"description": "Required when email is not provided",
"type": "integer",
"example": 123,
"nullable": true
},
"email": {
"description": "Required when user_id is not provided",
"type": "string",
"format": "email",
"example": "member@example.com",
"nullable": true
},
"first_name": {
"type": "string",
"example": "Miki",
"nullable": true
},
"last_name": {
"type": "string",
"example": "Birhanu",
"nullable": true
},
"phone_number": {
"type": "string",
"example": "+251900000000",
"nullable": true
},
"role_id": {
"type": "integer",
"example": 2
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"pending"
],
"example": "pending",
"nullable": true
},
"permissions": {
"description": "For each permission, omit both location_ids and station_ids to apply it to all workspaces",
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberWritePermissionPayload"
}
}
},
"type": "object"
},
"TeamMemberScopedStoreRequest": {
"required": [
"permissions"
],
"properties": {
"user_id": {
"description": "Required when email is not provided",
"type": "integer",
"example": 123,
"nullable": true
},
"email": {
"description": "Required when user_id is not provided",
"type": "string",
"format": "email",
"example": "member@example.com",
"nullable": true
},
"first_name": {
"type": "string",
"example": "Miki",
"nullable": true
},
"last_name": {
"type": "string",
"example": "Birhanu",
"nullable": true
},
"phone_number": {
"type": "string",
"example": "+251900000000",
"nullable": true
},
"role_id": {
"type": "integer",
"example": 2,
"nullable": true
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"pending"
],
"example": "pending",
"nullable": true
},
"permissions": {
"description": "Scope is derived from the route. Provide permission keys only.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberScopedWritePermissionPayload"
}
}
},
"type": "object"
},
"TeamMemberUpdateRequest": {
"required": [
"permissions"
],
"properties": {
"role_id": {
"type": "integer",
"example": 2,
"nullable": true
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"pending"
],
"example": "active",
"nullable": true
},
"first_name": {
"type": "string",
"example": "Miki",
"nullable": true
},
"last_name": {
"type": "string",
"example": "Birhanu",
"nullable": true
},
"email": {
"type": "string",
"format": "email",
"example": "member@example.com",
"nullable": true
},
"phone_number": {
"type": "string",
"example": "+251900000000",
"nullable": true
},
"permissions": {
"description": "For each permission, omit both location_ids and station_ids to apply it to all workspaces",
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberWritePermissionPayload"
}
}
},
"type": "object"
},
"TeamMemberScopedUpdateRequest": {
"required": [
"permissions"
],
"properties": {
"role_id": {
"type": "integer",
"example": 2,
"nullable": true
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"pending"
],
"example": "active",
"nullable": true
},
"permissions": {
"description": "Scope is derived from the route. Provide permission keys only.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberScopedWritePermissionPayload"
}
}
},
"type": "object"
},
"TeamMemberListResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team members retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberPayload"
}
},
"meta": {
"properties": {
"pagination": {
"properties": {
"total": {
"type": "integer",
"example": 100
},
"count": {
"type": "integer",
"example": 15
},
"per_page": {
"type": "integer",
"example": 15
},
"current_page": {
"type": "integer",
"example": 1
},
"total_pages": {
"type": "integer",
"example": 7
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"TeamMemberSingleResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team member updated successfully"
},
"data": {
"$ref": "#/components/schemas/TeamMemberPayload"
}
},
"type": "object"
},
"TeamMemberDetailResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Team member retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/TeamMemberDetailPayload"
}
},
"type": "object"
},
"TeamMemberDeleteResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization role deleted successfully"
},
"data": {
"nullable": true,
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/TeamMemberPayload"
}
]
}
},
"type": "object"
},
"ScheduleLinkResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization custom link retrieved or created successfully"
},
"data": {
"$ref": "#/components/schemas/ScheduleLinkResource"
}
},
"type": "object"
},
"ScheduleLinkListResponse": {
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Organization custom links retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ScheduleLinkResource"
}
}
},
"type": "object"
},
"ScheduleLinkResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"custom_path": {
"type": "string",
"example": "university-clinic-schedule"
},
"full_url": {
"type": "string",
"example": "https://app.migranium.com/schedule/university-clinic-schedule"
},
"qr_code_data": {
"type": "string",
"example": "https://app.migranium.com/schedule/university-clinic-schedule?through=qr",
"nullable": true
},
"type": {
"description": "'schedule' or 'walk_in'",
"type": "string",
"example": "schedule"
},
"entity_type": {
"type": "string",
"example": "Business"
},
"entity_data": {
"type": "object"
},
"is_active": {
"type": "boolean",
"example": true
},
"online_booking_enabled": {
"type": "boolean",
"example": true
},
"qr_code_enabled": {
"type": "boolean",
"example": true
},
"web_link_enabled": {
"type": "boolean",
"example": true
},
"is_visible": {
"type": "boolean",
"example": true
},
"total_visits": {
"type": "integer",
"example": 0
},
"total_bookings": {
"type": "integer",
"example": 0
},
"last_accessed_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"UpdateScheduleLinkRequest": {
"properties": {
"custom_path": {
"description": "Custom URL path (3-50 chars, alphanumeric and dashes only)",
"type": "string",
"maxLength": 50,
"minLength": 3,
"pattern": "^[a-zA-Z0-9-]+$",
"example": "university-clinic-updated"
},
"is_active": {
"description": "Whether link is active",
"type": "boolean",
"example": false
},
"online_booking_enabled": {
"description": "Whether online booking is enabled",
"type": "boolean",
"example": false
},
"qr_code_enabled": {
"description": "Whether QR code is enabled",
"type": "boolean",
"example": false
},
"web_link_enabled": {
"description": "Whether web link is enabled",
"type": "boolean",
"example": false
},
"is_visible": {
"description": "Whether link is visible",
"type": "boolean",
"example": false
}
},
"type": "object"
},
"WalkInLinkResource": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"custom_path": {
"type": "string",
"example": "university-clinic-walk_in"
},
"full_url": {
"type": "string",
"example": "https://app.migranium.com/join/university-clinic-walk_in"
},
"qr_code_data": {
"type": "string",
"example": "https://app.migranium.com/join/university-clinic-walk_in?through=qr",
"nullable": true
},
"type": {
"description": "'schedule' or 'walk_in'",
"type": "string",
"example": "walk_in"
},
"entity_type": {
"type": "string",
"example": "Business"
},
"entity_data": {
"type": "object"
},
"is_active": {
"type": "boolean",
"example": true
},
"online_booking_enabled": {
"type": "boolean",
"example": true
},
"qr_code_enabled": {
"type": "boolean",
"example": true
},
"web_link_enabled": {
"type": "boolean",
"example": true
},
"is_visible": {
"type": "boolean",
"example": true
},
"total_visits": {
"type": "integer",
"example": 0
},
"total_bookings": {
"type": "integer",
"example": 0
},
"last_accessed_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"ApplyOptionSelections": {
"description": "Workspace selection configuration for applying features to locations and stations",
"required": [
"apply_to_all",
"location_selections"
],
"properties": {
"apply_to_all": {
"description": "Whether to apply to all locations and stations in the business",
"type": "boolean",
"example": false
},
"location_selections": {
"description": "Array of location-specific selections",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApplyOptionLocationSelection"
}
}
},
"type": "object"
},
"ApplyOptionLocationSelection": {
"description": "Location-specific workspace selection configuration",
"required": [
"location_id",
"location_selected",
"all_station_selected"
],
"properties": {
"location_id": {
"description": "ID of the location",
"type": "integer",
"example": 1
},
"location_selected": {
"description": "Whether this location is selected",
"type": "boolean",
"example": true
},
"all_station_selected": {
"description": "Whether all stations in this location are selected",
"type": "boolean",
"example": false
},
"station_ids": {
"description": "Array of specific station IDs to select (required when all_station_selected is false)",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"type": "object"
},
"ApplyOptionValidationError": {
"description": "Validation error response for apply option selections",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"description": "Validation error details",
"properties": {
"apply_option_selections": {
"type": "array",
"items": {
"type": "string",
"example": "Workspace selections are required."
}
},
"apply_option_selections.location_selections": {
"type": "array",
"items": {
"type": "string",
"example": "Location selections are required."
}
},
"apply_option_selections.location_selections.*.location_id": {
"type": "array",
"items": {
"type": "string",
"example": "Selected location does not exist."
}
},
"apply_option_selections.location_selections.*.station_ids": {
"type": "array",
"items": {
"type": "string",
"example": "Some station_ids do not belong to location_id: 1"
}
}
},
"type": "object"
}
},
"type": "object"
},
"ApplyOptionPayload": {
"description": "Response payload containing current workspace selections",
"properties": {
"apply_to_all": {
"description": "Current apply to all setting",
"type": "boolean",
"example": false
},
"location_selections": {
"description": "Current location selections",
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationSelection"
}
}
},
"type": "object"
},
"BookingLinkRequest": {
"description": "Booking link request entity with workspace selections and client assignments",
"properties": {
"id": {
"description": "Unique identifier",
"type": "integer",
"example": 1
},
"uuid": {
"description": "Unique UUID for the booking link",
"type": "string",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"expire_option": {
"description": "Expiration strategy",
"type": "string",
"enum": [
"never",
"duration",
"specific_date"
],
"example": "duration"
},
"expire_duration": {
"description": "Duration value for expiration",
"type": "integer",
"example": 30
},
"expire_duration_unit": {
"description": "Duration unit for expiration",
"type": "string",
"enum": [
"hours",
"days",
"weeks",
"months"
],
"example": "days"
},
"expire_date": {
"description": "Specific expiration date",
"type": "string",
"format": "date",
"example": "2024-12-31"
},
"message": {
"description": "Custom message for clients",
"type": "string",
"example": "Book your appointment with us!"
},
"send_via_email": {
"description": "Whether to send notifications via email",
"type": "boolean",
"example": true
},
"send_via_sms": {
"description": "Whether to send notifications via SMS",
"type": "boolean",
"example": false
},
"booking_type": {
"description": "Type of booking",
"type": "string",
"enum": [
"schedule",
"walk_in"
],
"example": "schedule"
},
"business_id": {
"description": "ID of the business",
"type": "integer",
"example": 1
},
"admin_id": {
"description": "ID of the admin who created the request",
"type": "integer",
"example": 1
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:00:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:00:00Z"
},
"schedule_link": {
"description": "Full URL of the schedule link",
"type": "string",
"example": "https://example.com/booking/abc123"
},
"apply_option_selections": {
"$ref": "#/components/schemas/ApplyOptionPayload"
},
"client_requests": {
"description": "Array of client requests",
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientRequest"
}
}
},
"type": "object"
},
"ClientRequest": {
"description": "Client-specific booking request information",
"properties": {
"id": {
"description": "Client request ID",
"type": "integer",
"example": 1
},
"client_id": {
"description": "ID of the client",
"type": "integer",
"example": 1
},
"client_name": {
"description": "Name of the client",
"type": "string",
"example": "John Doe"
},
"schedule_link": {
"description": "Client-specific schedule link",
"type": "string",
"example": "https://example.com/booking/client123"
},
"is_booked": {
"description": "Whether the client has booked",
"type": "boolean",
"example": false
},
"is_email_sent": {
"description": "Whether email was sent",
"type": "boolean",
"example": true
},
"is_sms_sent": {
"description": "Whether SMS was sent",
"type": "boolean",
"example": false
},
"booked_at": {
"description": "When the client booked",
"type": "string",
"format": "date-time",
"example": "2024-01-15T14:30:00Z",
"nullable": true
},
"booking_id": {
"description": "ID of the actual booking",
"type": "integer",
"example": 123,
"nullable": true
}
},
"type": "object"
},
"BookingLinkRequestResource": {
"description": "Booking Link Request resource representation",
"properties": {
"id": {
"description": "ID of the booking link request",
"type": "integer",
"example": 123
},
"expire_option": {
"description": "Expire option type",
"type": "string",
"example": "after_duration"
},
"expire_duration": {
"description": "Duration value for expiration",
"type": "integer",
"example": 30
},
"expire_duration_unit": {
"description": "Unit of the expiration duration",
"type": "string",
"example": "minutes"
},
"expire_date": {
"description": "Expiration date/time",
"type": "string",
"format": "date-time",
"example": "2025-08-13T12:00:00Z"
},
"message": {
"description": "Message to send",
"type": "string",
"example": "Please confirm your booking"
},
"send_via_email": {
"description": "Whether to send via email",
"type": "boolean",
"example": true
},
"send_via_sms": {
"description": "Whether to send via SMS",
"type": "boolean",
"example": false
},
"schedule_link": {
"description": "Full URL of the schedule link",
"type": "string",
"format": "url",
"example": "https://example.com/schedule/abc123"
},
"booking_type": {
"description": "Type of booking",
"type": "string",
"example": "standard"
},
"apply_option_selections": {
"$ref": "#/components/schemas/ApplyOptionSelections"
},
"client_requests": {
"description": "List of client requests associated with this booking link request",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Client request ID",
"type": "integer",
"example": 10
},
"client_id": {
"description": "Client ID",
"type": "integer",
"example": 5
},
"client_name": {
"description": "Client's name",
"type": "string",
"example": "John Doe"
},
"schedule_link": {
"description": "Client's schedule link URL",
"type": "string",
"format": "url",
"example": "https://example.com/schedule/clientabc"
},
"is_booked": {
"description": "Whether this client request is booked",
"type": "boolean",
"example": true
},
"is_email_sent": {
"description": "Whether booking email has been sent",
"type": "boolean",
"example": false
},
"is_sms_sent": {
"description": "Whether booking SMS has been sent",
"type": "boolean",
"example": true
},
"booked_at": {
"description": "Booking timestamp",
"type": "string",
"format": "date-time",
"example": "2025-08-10T14:30:00Z",
"nullable": true
},
"booking_id": {
"description": "Booking ID if booked",
"type": "integer",
"example": 50,
"nullable": true
}
},
"type": "object"
}
},
"services": {
"description": "List of services associated with this booking link request",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Service ID",
"type": "integer",
"example": 10
},
"name": {
"description": "Service's name",
"type": "string",
"example": "Mental Health"
}
},
"type": "object"
}
}
},
"type": "object"
},
"CreateBookingLinkRequest": {
"description": "Request payload for creating a new booking link request",
"required": [
"client_ids",
"service_ids",
"apply_option_selections"
],
"properties": {
"booking_type": {
"description": "Type of booking",
"type": "string",
"enum": [
"schedule",
"walk_in"
],
"example": "schedule"
},
"message": {
"description": "Custom message for clients",
"type": "string",
"example": "Book your appointment with us!"
},
"send_via_email": {
"description": "Whether to send notifications via email",
"type": "boolean",
"example": true
},
"send_via_sms": {
"description": "Whether to send notifications via SMS",
"type": "boolean",
"example": false
},
"expire_option": {
"description": "Expiration strategy",
"type": "string",
"enum": [
"never",
"duration",
"specific_date"
],
"example": "duration"
},
"expire_duration": {
"description": "Duration value for expiration (required when expire_option is 'duration')",
"type": "integer",
"example": 30
},
"expire_duration_unit": {
"description": "Duration unit for expiration (required when expire_option is 'duration')",
"type": "string",
"enum": [
"hours",
"days",
"weeks",
"months"
],
"example": "days"
},
"expire_date": {
"description": "Specific expiration date (required when expire_option is 'specific_date')",
"type": "string",
"format": "date",
"example": "2024-12-31"
},
"client_ids": {
"description": "Array of client IDs to assign",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"service_ids": {
"description": "Array of service IDs to assign",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"apply_option_selections": {
"$ref": "#/components/schemas/ApplyOptionSelections"
}
},
"type": "object"
},
"BookingLinkRequestList": {
"description": "List of booking link requests",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking link requests retrieved successfully"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BookingLinkRequest"
}
}
},
"type": "object"
},
"BookingLinkRequestCreated": {
"description": "Response when a booking link request is created successfully",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Booking Link Created Successfully"
},
"data": {
"$ref": "#/components/schemas/BookingLinkRequest"
}
},
"type": "object"
},
"WorkspaceSelectionsResponse": {
"description": "Response containing workspace selections for a booking link request",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Workspace selections retrieved successfully"
},
"data": {
"$ref": "#/components/schemas/ApplyOptionPayload"
}
},
"type": "object"
},
"BookingLinkRequestValidationError": {
"description": "Validation error response for booking link request creation",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"description": "Validation error details",
"properties": {
"client_ids": {
"type": "array",
"items": {
"type": "string",
"example": "Client IDs are required."
}
},
"service_ids": {
"type": "array",
"items": {
"type": "string",
"example": "Service IDs are required."
}
},
"expire_duration": {
"type": "array",
"items": {
"type": "string",
"example": "Expire duration is required when expire option is duration."
}
},
"expire_date": {
"type": "array",
"items": {
"type": "string",
"example": "Expire date must be a date after or equal to today."
}
},
"apply_option_selections": {
"type": "array",
"items": {
"type": "string",
"example": "Workspace selections are required."
}
}
},
"type": "object"
}
},
"type": "object"
},
"FormCollection": {
"description": "Paginated collection of forms",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "forms retrieved successfully"
},
"data": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 50
},
"last_page": {
"type": "integer",
"example": 4
},
"from": {
"type": "integer",
"example": 1
},
"to": {
"type": "integer",
"example": 15
},
"data": {
"type": "array",
"items": {
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"status": {
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
},
"ApiResponse": {
"description": "Standard API response wrapper",
"properties": {
"success": {
"description": "Indicates if the request was successful",
"type": "boolean",
"example": true
},
"message": {
"description": "Human-readable message",
"type": "string",
"example": "Operation completed successfully"
},
"data": {
"description": "Response data (varies by endpoint)"
},
"meta": {
"description": "Additional metadata",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"request_id": {
"type": "string",
"example": "req_123456789"
},
"version": {
"type": "string",
"example": "1.0.0"
}
},
"type": "object"
}
},
"type": "object"
},
"PaginatedResponse": {
"description": "Paginated API response",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"type": "array",
"items": {}
},
"pagination": {
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 100
},
"last_page": {
"type": "integer",
"example": 7
},
"from": {
"type": "integer",
"example": 1
},
"to": {
"type": "integer",
"example": 15
},
"has_more_pages": {
"type": "boolean",
"example": true
},
"next_page_url": {
"type": "string",
"example": "/api/v1/users?page=2"
},
"prev_page_url": {
"type": "string",
"example": null
}
},
"type": "object"
}
},
"type": "object"
}
]
},
"ErrorResponse": {
"description": "Error response structure",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Operation failed"
},
"error_code": {
"type": "string",
"example": "VALIDATION_ERROR"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
},
"debug": {
"description": "Debug information (development only)",
"properties": {
"trace": {
"type": "string"
},
"file": {
"type": "string"
},
"line": {
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
},
"ValidationErrorResponse": {
"description": "Validation error response",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The given data was invalid."
},
"error_code": {
"type": "string",
"example": "VALIDATION_ERROR"
},
"errors": {
"description": "Field-specific validation errors",
"properties": {
"email": {
"type": "array",
"items": {
"type": "string",
"example": "The email has already been taken."
}
},
"password": {
"type": "array",
"items": {
"type": "string",
"example": "The password must be at least 8 characters."
}
}
},
"type": "object"
}
},
"type": "object"
},
"RateLimitResponse": {
"description": "Rate limit exceeded response",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Rate limit exceeded"
},
"error_code": {
"type": "string",
"example": "RATE_LIMIT_EXCEEDED"
},
"retry_after": {
"description": "Seconds to wait before retrying",
"type": "integer",
"example": 60
},
"limit": {
"description": "Total requests allowed per window",
"type": "integer",
"example": 100
},
"remaining": {
"description": "Remaining requests in current window",
"type": "integer",
"example": 0
}
},
"type": "object"
},
"FileUploadResponse": {
"description": "File upload response",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ApiResponse"
},
{
"properties": {
"data": {
"properties": {
"file_id": {
"type": "string",
"example": "file_123456789"
},
"filename": {
"type": "string",
"example": "document.pdf"
},
"original_name": {
"type": "string",
"example": "my-document.pdf"
},
"size": {
"description": "File size in bytes",
"type": "integer",
"example": 1024000
},
"mime_type": {
"type": "string",
"example": "application/pdf"
},
"url": {
"type": "string",
"example": "/storage/uploads/file_123456789.pdf"
},
"uploaded_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
}
},
"type": "object"
}
]
},
"HealthCheckResponse": {
"description": "Health check response",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy",
"degraded"
],
"example": "healthy"
},
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"version": {
"type": "string",
"example": "1.0.0"
},
"uptime": {
"description": "Server uptime in seconds",
"type": "integer",
"example": 86400
},
"services": {
"properties": {
"database": {
"properties": {
"status": {
"type": "string",
"example": "healthy"
},
"response_time": {
"description": "Response time in seconds",
"type": "number",
"example": 0.05
}
},
"type": "object"
},
"cache": {
"properties": {
"status": {
"type": "string",
"example": "healthy"
},
"response_time": {
"type": "number",
"example": 0.02
}
},
"type": "object"
},
"messaging": {
"properties": {
"status": {
"type": "string",
"example": "healthy"
},
"queue_size": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"Banner": {
"description": "Banner model with relationships",
"properties": {
"id": {
"description": "Banner ID",
"type": "integer",
"example": 1
},
"uuid": {
"description": "Banner UUID",
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"description": {
"description": "Banner description",
"type": "string",
"example": "Welcome to our service",
"nullable": true
},
"is_active": {
"description": "Banner active status",
"type": "boolean",
"example": true
},
"start_date": {
"description": "Banner start date",
"type": "string",
"format": "date-time",
"example": "2025-01-01T00:00:00Z",
"nullable": true
},
"end_date": {
"description": "Banner end date",
"type": "string",
"format": "date-time",
"example": "2025-12-31T23:59:59Z",
"nullable": true
},
"created_at": {
"description": "Creation timestamp",
"type": "string",
"format": "date-time",
"example": "2025-01-15T10:30:00Z"
},
"updated_at": {
"description": "Last update timestamp",
"type": "string",
"format": "date-time",
"example": "2025-01-15T10:30:00Z"
},
"banner_owns": {
"description": "Associated banner owns relationships",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"banner_id": {
"type": "integer",
"example": 1
},
"owningable_id": {
"type": "integer",
"example": 1
},
"owningable_type": {
"type": "string",
"example": "App\\\\Models\\\\Location"
},
"owningable": {
"description": "The owning model (Business, Location, or LocationStation)"
}
},
"type": "object"
}
}
},
"type": "object"
},
"DisplaySettings": {
"description": "Display settings for business",
"properties": {
"name": {
"description": "Business name",
"type": "string",
"example": "Business Name"
},
"display_title": {
"description": "Business display title",
"type": "string",
"example": "Business Display Title"
},
"description": {
"description": "Business description",
"type": "string",
"example": "Business Description"
},
"logo": {
"description": "Business logo URL",
"type": "string",
"example": "https://example.com/logo.png"
},
"banner": {
"description": "Business banner image URL",
"type": "string",
"example": "https://example.com/banner.png"
},
"background_image": {
"description": "Background image URL",
"type": "string",
"example": "https://example.com/background.png"
},
"secondary_cta_title": {
"description": "Secondary call-to-action title",
"type": "string",
"example": "Contact Us"
},
"secondary_cta_url": {
"description": "Secondary call-to-action URL",
"type": "string",
"example": "https://example.com/contact"
},
"background_color": {
"description": "Background color",
"type": "string",
"example": "#FFFFFF"
},
"theme_text_color": {
"description": "Theme text color",
"type": "string",
"example": "#000000"
},
"theme": {
"description": "Theme name",
"type": "string",
"example": "light"
}
},
"type": "object"
},
"SecurityOption": {
"description": "Security option for client portal authentication",
"properties": {
"type": {
"description": "Type of security validation required",
"type": "string",
"enum": [
"personal_info",
"validators",
"sso",
"auth_client_id",
"through_invitation"
],
"example": "personal_info"
}
},
"type": "object"
},
"VerificationSettings": {
"description": "Verification settings for client portal",
"properties": {
"question": {
"description": "Verification question",
"type": "string",
"example": "What is your favorite color?"
},
"redirect_url": {
"description": "URL to redirect to for verification",
"type": "string",
"example": "https://example.com/verify"
},
"redirect_answer_value": {
"description": "Expected answer value for verification",
"type": "string",
"example": "blue"
}
},
"type": "object"
},
"BaseListRequest": {
"description": "Base request for list endpoints with pagination, search, and sorting",
"properties": {
"sort_direction": {
"description": "Sort direction",
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
"type": "object"
},
"PaginationFilterRequest": {
"title": "Pagination and Filter Request",
"description": "Base request schema for endpoints that support pagination, searching, and sorting.",
"properties": {
"page": {
"description": "The page number to retrieve.",
"type": "integer",
"format": "int32",
"default": 1,
"example": 1
},
"per_page": {
"description": "The number of items per page.",
"type": "integer",
"format": "int32",
"default": 15,
"example": 15
},
"search": {
"description": "A search term to filter results.",
"type": "string",
"example": "John Doe"
},
"sort_by": {
"description": "The field to sort by. The allowed fields depend on the specific endpoint.",
"type": "string",
"example": "created_at"
},
"sort_direction": {
"description": "The direction to sort in.",
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
"type": "object"
},
"BookingListRequest": {
"description": "Request for listing bookings with filters and pagination",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseListRequest"
},
{
"properties": {
"service": {
"description": "Filter by a single service ID",
"type": "integer",
"example": 5
}
},
"type": "object"
}
]
},
"BulkSyncCustomIntakesRequest": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"nullable": true
},
"name": {
"description": "Field name. Must be unique within the business/location/station context and within the request body array.",
"type": "string",
"maxLength": 255,
"nullable": false
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
],
"nullable": false
},
"apply_to": {
"type": "string",
"enum": [
"all",
"waitlist_only",
"schedule_only"
],
"nullable": false
},
"field_requirement": {
"type": "string",
"enum": [
"no",
"yes",
"conditional"
],
"nullable": false
},
"allow_multiple": {
"type": "boolean",
"example": false
},
"long_text": {
"type": "boolean",
"example": false
},
"order": {
"type": "integer",
"minimum": 0,
"example": 1
},
"is_visible": {
"type": "boolean",
"example": true
},
"is_business_specific": {
"description": "Whether this intake is specific to the business/organization level",
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"required": [
"label"
],
"properties": {
"id": {
"type": "integer",
"nullable": true
},
"label": {
"type": "string",
"maxLength": 255
},
"order": {
"type": "integer",
"minimum": 0,
"nullable": true
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
}
},
"StoreClientCategoryRequest": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Name of the category",
"type": "string",
"maxLength": 255
},
"color": {
"description": "Color code for the category",
"type": "string",
"maxLength": 25,
"nullable": true
},
"description": {
"description": "Description of the category",
"type": "string",
"nullable": true
},
"type": {
"description": "Type of category",
"type": "string",
"nullable": true
},
"conditions": {
"description": "Array of conditions for conditional categories",
"type": "array",
"items": {
"properties": {
"condition_type": {
"type": "string",
"enum": [
"registration_date",
"last_visit",
"information_check",
"priority"
]
},
"operator": {
"type": "string",
"enum": [
"before_date",
"after_date",
"on_date",
"during_range",
"outside_of_range",
"equals",
"not_equals",
"contains",
"not_contains",
"greater_than",
"less_than",
"greater_than_or_equal",
"less_than_or_equal"
]
},
"conditional_value": {
"description": "Value for the condition",
"type": "string"
},
"date_range_start": {
"description": "Start date for range operators",
"type": "string",
"format": "date"
},
"date_range_end": {
"description": "End date for range operators",
"type": "string",
"format": "date"
},
"information_type": {
"type": "string",
"enum": [
"form_answer",
"custom_intake_answer"
]
},
"form_question_id": {
"description": "UUID of form question",
"type": "string"
},
"custom_intake_id": {
"description": "ID of custom intake",
"type": "integer"
}
},
"type": "object"
},
"nullable": true
},
"location_ids": {
"description": "Array of location IDs",
"type": "array",
"items": {
"type": "integer"
},
"nullable": true
}
},
"type": "object"
},
"UpdateClientCategoryRequest": {
"required": [],
"properties": {
"name": {
"description": "Name of the category",
"type": "string",
"maxLength": 255
},
"color": {
"description": "Color code for the category",
"type": "string",
"maxLength": 25,
"nullable": true
},
"description": {
"description": "Description of the category",
"type": "string",
"nullable": true
},
"type": {
"description": "Type of category",
"type": "string",
"enum": [
"manual",
"conditional"
],
"nullable": true
},
"conditions": {
"description": "Array of conditions for conditional categories",
"type": "array",
"items": {
"properties": {
"condition_type": {
"type": "string",
"enum": [
"registration_date",
"last_visit",
"information_check",
"priority"
]
},
"operator": {
"type": "string",
"enum": [
"before_date",
"after_date",
"on_date",
"during_range",
"outside_of_range",
"equals",
"not_equals",
"contains",
"not_contains",
"greater_than",
"less_than",
"greater_than_or_equal",
"less_than_or_equal"
]
},
"conditional_value": {
"description": "Value for the condition",
"type": "string"
},
"date_range_start": {
"description": "Start date for range operators",
"type": "string",
"format": "date"
},
"date_range_end": {
"description": "End date for range operators",
"type": "string",
"format": "date"
},
"information_type": {
"type": "string",
"enum": [
"form_answer",
"custom_intake_answer"
]
},
"form_question_id": {
"description": "UUID of form question",
"type": "string"
},
"custom_intake_id": {
"description": "ID of custom intake",
"type": "integer"
}
},
"type": "object"
},
"nullable": true
},
"location_ids": {
"description": "Array of location IDs",
"type": "array",
"items": {
"type": "integer"
},
"nullable": true
},
"station_ids": {
"description": "Array of station IDs",
"type": "array",
"items": {
"type": "integer"
},
"nullable": true
},
"location_selections": {
"description": "Location selections with station assignments",
"type": "array",
"items": {
"required": [
"location_id"
],
"properties": {
"location_id": {
"type": "integer",
"example": 1
},
"all_stations": {
"type": "boolean",
"example": true
},
"station_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
},
"AttributeSyncForImportRequest": {
"description": "Array of attribute objects for import synchronization",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Attribute ID for existing attributes",
"type": "integer",
"example": 1,
"nullable": true
},
"label": {
"description": "Display title for the attribute on Migranium",
"type": "string",
"maxLength": 255,
"example": "First Name",
"nullable": true
},
"import_column_name": {
"description": "Column name for import mapping",
"type": "string",
"maxLength": 255,
"example": "first_name",
"nullable": true
},
"type": {
"description": "Attribute type",
"type": "string",
"enum": [
"text",
"number",
"date",
"select",
"boolean",
"email",
"phone",
"attachment"
],
"example": "text",
"nullable": true
},
"is_required": {
"description": "Whether the attribute is required",
"type": "boolean",
"example": false,
"nullable": true
},
"is_validator": {
"description": "Whether the attribute is used for validation",
"type": "boolean",
"example": false,
"nullable": true
},
"options": {
"description": "Options for select/dropdown types",
"type": "array",
"items": {
"properties": {
"label": {
"description": "Option label",
"type": "string",
"example": "Option 1",
"nullable": true
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
},
"example": [
{
"id": 1,
"label": "First Name",
"import_column_name": "first_name",
"type": "text",
"is_required": true,
"is_validator": false
},
{
"id": 2,
"label": "Last Visit Date",
"import_column_name": "last_visit",
"type": "date",
"is_required": false,
"is_validator": true
}
]
},
"ClientAttributeSettingRequest": {
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"description": "Attribute ID for updates, null for new attributes",
"type": "integer",
"nullable": true
},
"label": {
"description": "Display label for the attribute",
"type": "string"
},
"type": {
"description": "Attribute type (text, number, date, dropdown, etc.)",
"type": "string"
},
"options": {
"description": "Options for dropdown/select types",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"nullable": true
},
"label": {
"type": "string"
},
"order": {
"type": "integer"
}
},
"type": "object"
},
"nullable": true
},
"is_required": {
"type": "boolean",
"default": false
},
"is_validator": {
"type": "boolean",
"default": false
}
},
"type": "object"
}
}
},
"type": "object"
},
"StoreClientAttributeRequest": {
"description": "Request for creating a new client attribute",
"required": [
"label",
"type"
],
"properties": {
"label": {
"description": "Display label for the attribute",
"type": "string",
"maxLength": 255,
"example": "Allergies"
},
"type": {
"description": "Attribute type",
"type": "string",
"enum": [
"text",
"number",
"date",
"select",
"boolean",
"email",
"phone",
"attachment"
],
"example": "text"
},
"options": {
"description": "Options for select/dropdown types",
"type": "array",
"items": {
"properties": {
"label": {
"description": "Option label",
"type": "string",
"example": "Peanut"
},
"order": {
"description": "Display order",
"type": "integer",
"example": 1
}
},
"type": "object"
},
"nullable": true
},
"is_required": {
"description": "Whether the attribute is required",
"type": "boolean",
"default": false,
"example": false
},
"is_validator": {
"description": "Whether the attribute is used for validation",
"type": "boolean",
"default": false,
"example": false
},
"import_column_name": {
"description": "Column name for import mapping",
"type": "string",
"maxLength": 255,
"example": "allergies",
"nullable": true
}
},
"type": "object",
"example": {
"label": "Allergies",
"type": "select",
"options": [
{
"label": "Peanut",
"order": 1
},
{
"label": "Dairy",
"order": 2
}
],
"is_required": true,
"is_validator": false,
"import_column_name": "allergies"
}
},
"PublicStoreFormResponseRequest": {
"description": "Public form response request. The form_id is extracted from the URL path parameter, not the request body.",
"required": [
"responses"
],
"properties": {
"customer_id": {
"description": "Optional client ID to associate with this response",
"type": "integer",
"example": 123,
"nullable": true
},
"session_id": {
"description": "Optional session identifier for tracking",
"type": "string",
"example": "sess_abc123",
"nullable": true
},
"request_id": {
"description": "Optional form request client UUID for tracking form request submissions",
"type": "string",
"example": "14b8fec6-3c9d-4778-a45a-242d927b0abf",
"nullable": true
},
"location_id": {
"description": "Optional location ID for direct form submissions (when no request_id)",
"type": "integer",
"example": 1,
"nullable": true
},
"station_id": {
"description": "Optional station ID for direct form submissions (when no request_id)",
"type": "integer",
"example": 1,
"nullable": true
},
"responses": {
"description": "Array of field responses",
"type": "array",
"items": {
"required": [
"field_id",
"value",
"value_type"
],
"properties": {
"field_id": {
"description": "Field UUID",
"type": "string",
"format": "uuid",
"example": "f1e2d3c4-5678-90ab-cdef-1234567890ab"
},
"value": {
"description": "Field response value",
"oneOf": [
{
"type": "string",
"example": "John Doe"
},
{
"type": "number",
"example": 25
},
{
"type": "boolean",
"example": true
},
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"option1",
"option2"
]
}
]
},
"value_type": {
"description": "Type of the value (text, number, email, etc.)",
"type": "string",
"example": "text"
}
},
"type": "object"
}
}
},
"type": "object"
},
"StoreFormResponseRequest": {
"required": [
"form_id",
"session_id",
"status",
"responses"
],
"properties": {
"form_id": {
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"session_id": {
"type": "string",
"example": "sess_abc123",
"nullable": true
},
"status": {
"type": "string",
"enum": [
"pending",
"completed",
"blocked",
"approved",
"declined"
],
"example": "completed",
"nullable": true
},
"block_reason": {
"type": "string",
"example": "User not eligible."
},
"rating": {
"type": "number",
"format": "float",
"example": 4.5,
"nullable": true
},
"general_feedback": {
"type": "string",
"example": "Great job!",
"nullable": true
},
"station_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"location_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"customer_id": {
"type": "integer",
"example": 2,
"nullable": true
},
"service_id": {
"type": "integer",
"example": 3,
"nullable": true
},
"responses": {
"type": "array",
"items": {
"required": [
"field_id",
"value",
"value_type"
],
"properties": {
"field_id": {
"type": "string",
"format": "uuid",
"example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"value": {
"type": "string",
"example": "John Doe"
},
"value_type": {
"type": "string",
"example": "text"
}
},
"type": "object"
}
},
"client_configs": {
"description": "Required for enquiry forms. Contains client information based on business attribute configuration.",
"properties": {
"first_name": {
"description": "Client first name (system field)",
"type": "string",
"example": "John"
},
"last_name": {
"description": "Client last name (system field)",
"type": "string",
"example": "Doe"
},
"email": {
"description": "Client email (system field)",
"type": "string",
"format": "email",
"example": "john.doe@example.com"
},
"phone_number": {
"description": "Client phone number (system field)",
"type": "string",
"example": "+1234567890"
},
"attribute_values": {
"description": "Custom attribute values where key is attribute ID and value is the attribute value",
"type": "object",
"example": {
"123": "Male",
"456": "25"
}
}
},
"type": "object",
"example": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+1234567890",
"attribute_values": {
"123": "Male",
"456": "25"
}
}
}
},
"type": "object"
},
"UpdateFormResponseRequest": {
"properties": {
"form_id": {
"type": "string",
"format": "uuid",
"example": "..."
},
"session_id": {
"type": "string",
"example": "sess_abc123"
},
"status": {
"type": "string",
"enum": [
"pending",
"completed",
"blocked",
"approved",
"declined"
],
"example": "completed"
},
"block_reason": {
"type": "string",
"example": "..."
},
"rating": {
"type": "number",
"format": "float",
"example": 4.5,
"nullable": true
},
"general_feedback": {
"type": "string",
"example": "...",
"nullable": true
},
"location_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"station_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"customer_id": {
"type": "integer",
"example": 2,
"nullable": true
},
"service_id": {
"type": "integer",
"example": 3,
"nullable": true
},
"responses": {
"type": "array",
"items": {
"required": [
"field_id",
"value",
"value_type"
],
"properties": {
"field_id": {
"type": "string",
"format": "uuid",
"example": "..."
},
"value": {
"type": "string",
"example": "John Doe"
},
"value_type": {
"type": "string",
"example": "text"
}
},
"type": "object"
}
}
},
"type": "object"
},
"FormUpdateRequest": {
"title": "Form Update Request",
"description": "Request body for updating a form",
"properties": {
"type": {
"description": "Type of the form",
"type": "string",
"example": "service"
},
"status": {
"description": "Status of the form",
"type": "string",
"example": "draft"
},
"name": {
"description": "Name of the form",
"type": "string",
"maxLength": 255,
"example": "My Form"
},
"description": {
"description": "Description of the form",
"type": "string",
"example": "This is a form."
},
"service_id": {
"description": "Service ID (backward compatibility)",
"type": "integer",
"example": 1,
"nullable": true
},
"service_ids": {
"description": "Array of service IDs",
"type": "array",
"items": {
"type": "integer"
}
},
"location_id": {
"description": "Location ID (backward compatibility)",
"type": "integer",
"example": 1,
"nullable": true
},
"location_ids": {
"description": "Array of location IDs",
"type": "array",
"items": {
"type": "integer"
}
},
"station_id": {
"description": "Station ID (backward compatibility)",
"type": "integer",
"example": 1,
"nullable": true
},
"station_ids": {
"description": "Array of station IDs",
"type": "array",
"items": {
"type": "integer"
}
},
"logo_url": {
"description": "Logo URL",
"type": "string",
"format": "url",
"maxLength": 2048,
"example": "https://example.com/logo.png"
},
"banner_url": {
"description": "Banner URL",
"type": "string",
"format": "url",
"maxLength": 2048,
"example": "https://example.com/banner.png"
},
"success_message": {
"description": "Success message",
"type": "string",
"maxLength": 1000,
"example": "Thank you for submitting!"
},
"submit_button_title": {
"description": "Submit button title",
"type": "string",
"maxLength": 100,
"example": "Submit"
},
"block_message": {
"description": "Block message",
"type": "string",
"maxLength": 1000,
"example": "Form is blocked."
},
"is_auto_approve": {
"description": "Auto approve flag",
"type": "boolean"
},
"validation_fields": {
"description": "Validation fields",
"type": "array",
"items": {
"type": "string"
}
},
"sections": {
"description": "Form sections",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Section ID",
"type": "string",
"maxLength": 50,
"example": "section-uuid"
},
"title": {
"description": "Section title",
"type": "string",
"maxLength": 255,
"example": "Section 1"
},
"description": {
"description": "Section description",
"type": "string",
"maxLength": 1000
},
"flow_action": {
"description": "Section flow action",
"type": "string",
"example": "go_to_section"
},
"flow_target_section_id": {
"description": "Target section ID for flow",
"type": "string",
"maxLength": 50,
"example": "section-uuid-2"
},
"order": {
"description": "Section order",
"type": "integer"
},
"fields": {
"description": "Fields in the section",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Field ID",
"type": "string",
"maxLength": 50,
"example": "field-uuid"
},
"type": {
"description": "Field type",
"type": "string",
"example": "text"
},
"title": {
"description": "Field title",
"type": "string",
"maxLength": 255,
"example": "First Name"
},
"placeholder": {
"description": "Field placeholder",
"type": "string",
"maxLength": 255,
"example": "Enter your name"
},
"description": {
"description": "Field description",
"type": "string",
"maxLength": 1000
},
"required": {
"description": "Is field required",
"type": "boolean"
},
"order": {
"description": "Field order",
"type": "integer"
},
"image": {
"description": "Field image URL",
"type": "string",
"format": "url",
"maxLength": 2048
},
"info_text_value": {
"description": "Info text value",
"type": "string"
},
"approved_formats": {
"description": "Approved formats",
"type": "array",
"items": {
"type": "string",
"maxLength": 10
}
},
"date_validation": {
"description": "Date validation",
"properties": {
"min_date": {
"description": "Minimum date",
"type": "string",
"format": "date"
},
"max_date": {
"description": "Maximum date",
"type": "string",
"format": "date"
}
},
"type": "object"
},
"selection_limit": {
"description": "Selection limit for multi_select",
"type": "integer",
"minimum": 1
},
"visibility_conditions": {
"description": "Visibility conditions",
"type": "array",
"items": {
"properties": {
"trigger_field_id": {
"description": "Trigger field ID",
"type": "string",
"maxLength": 50
},
"operator": {
"description": "Operator",
"type": "string"
},
"value": {
"description": "Value for condition"
},
"action": {
"description": "Action to take",
"type": "string"
}
},
"type": "object"
}
},
"default_configs": {
"description": "Default value configurations",
"type": "array",
"items": {
"properties": {
"source_field_id": {
"description": "Source field ID",
"type": "string",
"maxLength": 50
},
"source_answer_value": {
"description": "Source answer value"
},
"default_value": {
"description": "Default value"
}
},
"type": "object"
}
},
"options": {
"description": "Options for select/radio/checkbox fields",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Option ID",
"type": "string",
"maxLength": 50
},
"value": {
"description": "Option value"
},
"order": {
"description": "Option order",
"type": "integer",
"minimum": 0
},
"conditions": {
"description": "Option conditions",
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"collect_rating": {
"description": "Collect rating (feedback forms only)",
"type": "boolean"
},
"collect_general_feedback": {
"description": "Collect general feedback (feedback forms only)",
"type": "boolean"
},
"general_feedback_title": {
"description": "General feedback title (feedback forms only)",
"type": "string",
"maxLength": 255
}
},
"type": "object"
},
"PartialUpdateFormRequest": {
"description": "All fields are optional for partial updates",
"properties": {
"name": {
"description": "Form name",
"type": "string",
"example": "Updated Form Name"
},
"description": {
"description": "Form description",
"type": "string",
"example": "Updated description"
},
"status": {
"description": "Form status",
"type": "string",
"enum": [
"draft",
"live",
"unpublished"
],
"example": "live"
},
"logo_url": {
"description": "Logo URL",
"type": "string",
"format": "url",
"example": "https://example.com/logo.png"
},
"banner_url": {
"description": "Banner URL",
"type": "string",
"format": "url",
"example": "https://example.com/banner.png"
},
"success_message": {
"description": "Success message",
"type": "string",
"example": "Thank you for your submission!"
},
"submit_button_title": {
"description": "Submit button text",
"type": "string",
"example": "Submit Form"
},
"block_message": {
"description": "Block message",
"type": "string",
"example": "This form is currently unavailable"
},
"service_id": {
"description": "Associated service ID",
"type": "integer",
"example": 5
},
"location_id": {
"description": "Associated location ID",
"type": "integer",
"example": 3
},
"station_id": {
"description": "Associated station ID",
"type": "integer",
"example": 4
},
"collect_rating": {
"description": "Enable rating collection (feedback forms)",
"type": "boolean",
"example": true
},
"collect_general_feedback": {
"description": "Enable general feedback (feedback forms)",
"type": "boolean",
"example": false
},
"general_feedback_title": {
"description": "General feedback title",
"type": "string",
"example": "Additional Comments"
},
"is_auto_approve": {
"description": "Auto-approve submissions (intake forms only)",
"type": "boolean",
"example": false
},
"validation_fields": {
"description": "Custom validation fields",
"type": "array",
"items": {
"type": "string"
},
"example": [
"email",
"phone"
]
},
"sections": {
"description": "Form sections (complete replacement - existing sections will be deleted and replaced)",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Section ID (optional for new sections)",
"type": "string",
"example": "section_1"
},
"title": {
"description": "Section title",
"type": "string",
"example": "Personal Information"
},
"description": {
"description": "Section description",
"type": "string",
"example": "Please provide your details"
},
"order": {
"description": "Display order",
"type": "integer",
"example": 1
},
"flow_action": {
"type": "string",
"enum": [
"submit",
"continue",
"block_form"
],
"example": "continue"
},
"flow_target_section_id": {
"description": "Next section ID",
"type": "string",
"example": "section_2"
},
"fields": {
"type": "array",
"items": {
"properties": {
"id": {
"description": "Field ID (optional for new fields)",
"type": "string",
"example": "field_1"
},
"type": {
"description": "Field type",
"type": "string",
"example": "text"
},
"title": {
"description": "Field title",
"type": "string",
"example": "Full Name"
},
"required": {
"description": "Is required",
"type": "boolean",
"example": true
},
"order": {
"description": "Display order",
"type": "integer",
"example": 1
},
"options": {
"description": "Field options (for dropdown, radio, checkbox fields)",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "option_1"
},
"value": {
"type": "string",
"example": "yes"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"PartnerFilterRequest": {
"title": "Partner Filter Request",
"description": "Request schema for filtering referral partners with pagination, search, and sorting capabilities.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaginationFilterRequest"
},
{
"properties": {
"type": {
"description": "Filter by a single partner type ID.",
"type": "integer",
"example": 1
},
"types": {
"description": "Filter by multiple partner type IDs. Can be an array or comma-separated string.",
"oneOf": [
{
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
},
{
"type": "string",
"example": "1,2,3"
}
]
},
"referral_type": {
"description": "Filter by a single referral type.",
"type": "string",
"enum": [
"inbound",
"outbound",
"both"
],
"example": "inbound"
},
"referral_types": {
"description": "Filter by multiple referral types. Can be an array or comma-separated string.",
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"inbound",
"outbound",
"both"
]
},
"example": [
"inbound",
"outbound"
]
},
{
"type": "string",
"example": "inbound,outbound"
}
]
},
"service_id": {
"description": "Filter by a specific service ID.",
"type": "integer",
"example": 5
}
},
"type": "object"
}
]
},
"PeSettingRequest": {
"description": "All fields are optional for partial updates of patient experience settings",
"properties": {
"is_chat_enabled": {
"description": "Whether chat is enabled for patients",
"type": "boolean",
"example": true,
"nullable": true
},
"allow_profile_update": {
"description": "Whether patients are allowed to update their profile",
"type": "boolean",
"example": true,
"nullable": true
},
"allow_two_way_chatting": {
"description": "Whether two-way chatting is enabled",
"type": "boolean",
"example": true,
"nullable": true
},
"sign_up_options": {
"description": "Available sign-up options for patients. Valid values: email_password, phone_number_otp, gmail, microsoft, apple, custom_sso",
"type": "array",
"items": {
"type": "string",
"enum": [
"email_password",
"phone_number_otp",
"gmail",
"microsoft",
"apple",
"custom_sso"
]
},
"example": [
"email_password",
"gmail",
"microsoft"
],
"nullable": true
},
"allow_intake_view": {
"description": "Whether patients are allowed to view intake forms",
"type": "boolean",
"example": true,
"nullable": true
},
"allow_intake_edit": {
"description": "Whether patients are allowed to edit intake forms",
"type": "boolean",
"example": false,
"nullable": true
},
"notification_enabled": {
"description": "Whether notifications are enabled for patients",
"type": "boolean",
"example": true,
"nullable": true
},
"sms_notification_enabled": {
"description": "Whether SMS notifications are enabled for patients",
"type": "boolean",
"example": true,
"nullable": true
},
"email_notification_enabled": {
"description": "Whether email notifications are enabled for patients",
"type": "boolean",
"example": true,
"nullable": true
},
"attribute_preferences": {
"description": "Client attribute permissions for patient experience",
"type": "array",
"items": {
"required": [
"id",
"client_allowed_to_view",
"client_allowed_to_edit"
],
"properties": {
"id": {
"description": "Client attribute ID",
"type": "integer",
"example": 1
},
"client_allowed_to_view": {
"description": "Whether clients can view this attribute",
"type": "boolean",
"example": true
},
"client_allowed_to_edit": {
"description": "Whether clients can edit this attribute",
"type": "boolean",
"example": false
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
},
"StoreProviderRequest": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Provider name. Must be unique within the organization.",
"type": "string",
"example": "Dr. John Smith"
},
"image": {
"description": "Provider image URL. Must be a valid image URL.",
"type": "string",
"format": "url",
"example": "https://example.com/images/provider.jpg",
"nullable": true
},
"description": {
"description": "Provider description",
"type": "string",
"example": "Primary care physician with 10 years of experience",
"nullable": true
},
"email": {
"description": "Provider email address",
"type": "string",
"format": "email",
"example": "john.smith@example.com",
"nullable": true
},
"phone_number": {
"description": "Provider phone number",
"type": "string",
"example": "+1-555-0123",
"nullable": true
},
"service_provider_first_name": {
"description": "Service provider first name",
"type": "string",
"example": "John",
"nullable": true
},
"service_provider_last_name": {
"description": "Service provider last name",
"type": "string",
"example": "Smith",
"nullable": true
},
"service_provider_email": {
"description": "Service provider email address",
"type": "string",
"format": "email",
"example": "john.smith@example.com",
"nullable": true
},
"service_provider_phone": {
"description": "Service provider phone number",
"type": "string",
"example": "+1-555-0123",
"nullable": true
},
"location_ids": {
"description": "Array of location IDs to associate with this provider",
"type": "array",
"items": {
"type": "integer",
"example": 1
},
"nullable": true
}
},
"type": "object"
},
"UpdateProviderRequest": {
"description": "All fields are optional for partial updates",
"properties": {
"name": {
"description": "Provider name. Must be unique within the organization.",
"type": "string",
"example": "Dr. John Smith"
},
"image": {
"description": "Provider image URL. Must be a valid image URL.",
"type": "string",
"format": "url",
"example": "https://example.com/images/provider.jpg",
"nullable": true
},
"description": {
"description": "Provider description",
"type": "string",
"example": "Primary care physician with 10 years of experience",
"nullable": true
},
"email": {
"description": "Provider email address",
"type": "string",
"format": "email",
"example": "john.smith@example.com",
"nullable": true
},
"phone_number": {
"description": "Provider phone number",
"type": "string",
"example": "+1-555-0123",
"nullable": true
},
"location_ids": {
"description": "Array of location IDs to associate with this provider",
"type": "array",
"items": {
"type": "integer",
"example": 1
},
"nullable": true
},
"is_active": {
"description": "Whether the provider is active",
"type": "boolean",
"example": true,
"nullable": true
}
},
"type": "object"
},
"UserQueuePreferenceUpdateRequest": {
"title": "User Queue Preference Update Request",
"description": "Request body for updating user queue preferences",
"properties": {
"selected_location_id": {
"description": "Location ID to filter the queue by",
"type": "integer",
"example": 1
},
"provider_selections": {
"properties": {
"all_selected": {
"type": "boolean",
"example": true
},
"selected": {
"description": "List of provider/station IDs",
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
"type": "object"
},
"service_selections": {
"properties": {
"all_selected": {
"type": "boolean",
"example": true
},
"selected": {
"description": "List of service IDs",
"type": "array",
"items": {
"type": "integer"
},
"example": [
4,
5
]
}
},
"type": "object"
},
"joined_from": {
"properties": {
"all_selected": {
"type": "boolean",
"example": true
},
"selected": {
"description": "List of booking sources",
"type": "array",
"items": {
"type": "string"
},
"example": [
"Admin",
"Link",
"Web",
"QR"
]
}
},
"type": "object"
},
"show_walk_in": {
"type": "boolean",
"example": true
},
"show_scheduled": {
"type": "boolean",
"example": true
},
"show_pending_appointments": {
"type": "boolean",
"example": false
},
"show_provider": {
"type": "boolean",
"example": true
},
"show_service": {
"type": "boolean",
"example": true
},
"show_joined_from": {
"type": "boolean",
"example": false
},
"show_appointment_method": {
"type": "boolean",
"example": true
},
"show_appointment_type": {
"type": "boolean",
"example": true
},
"auto_flow": {
"type": "boolean",
"example": true
},
"is_queue_active": {
"type": "boolean",
"example": true
},
"allow_toast_notifications": {
"type": "boolean",
"example": true
},
"allow_walk_in_appointments": {
"type": "boolean",
"example": true
},
"auto_approve_walk_in_appointments": {
"type": "boolean",
"example": false
},
"max_patients_allowed_to_join": {
"type": "integer",
"example": 50
},
"popup_duration": {
"type": "integer",
"example": 5
},
"page_layout": {
"type": "string",
"enum": [
"column",
"grid"
],
"example": "column"
}
},
"type": "object"
},
"BaseReferralServiceRequest": {
"title": "Base Referral Service Request",
"description": "Base properties for creating or updating a referral service.",
"properties": {
"name": {
"description": "The name of the referral service.",
"type": "string",
"example": "Cardiology Consultation"
},
"description": {
"description": "A detailed description of the service.",
"type": "string",
"example": "A comprehensive consultation with a cardiology specialist."
},
"existing_service_id": {
"description": "The ID of an existing core service to link to.",
"type": "integer",
"example": 12
},
"is_available": {
"description": "Flag to indicate if the service is currently available.",
"type": "boolean",
"example": true
},
"auto_approve": {
"description": "Flag to indicate if referrals for this service should be auto-approved.",
"type": "boolean",
"example": false
},
"is_visible": {
"description": "Flag to indicate if the service is visible to partners.",
"type": "boolean",
"example": true
},
"time_in_minute": {
"description": "The duration of the service in minutes.",
"type": "integer",
"example": 60
},
"type": {
"description": "The type of referral.",
"type": "string",
"enum": [
"incoming",
"outgoing",
"both"
],
"example": "outgoing"
},
"incoming_partner_ids": {
"description": "An array of partner business IDs that can refer for this service.",
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"outgoing_partner_ids": {
"description": "An array of partner business IDs to whom referrals can be sent for this service.",
"type": "array",
"items": {
"type": "integer",
"example": 2
}
}
},
"type": "object"
},
"ReferralServiceFilterRequest": {
"title": "Referral Service Filter Request",
"description": "Schema for filtering referral services with pagination, sorting, and specific filters.",
"allOf": [
{
"$ref": "#/components/schemas/PaginationFilterRequest"
},
{
"properties": {
"type": {
"description": "Filter by service type. Can be a single value or a comma-separated list of values. See the ServiceType enum for available options.",
"type": "string",
"example": "outgoing,incoming"
},
"referral_type": {
"description": "Filter by referral type. Can be a single value or a comma-separated list of values. See the ReferralType enum for available options.",
"type": "string",
"example": "referral_incoming,internal"
},
"partner_id": {
"description": "Filter by one or more partner IDs. Accepts a comma-separated string of IDs or a JSON array of IDs.",
"type": "string",
"example": "1,2,3"
},
"sort_by": {
"description": "Allowed sort fields: `name`, `type`, `created_at`, `partner_count`."
}
},
"type": "object"
}
]
},
"StoreReferralServiceRequest": {
"title": "Store Referral Service Request",
"description": "Request body for creating a new referral service.",
"allOf": [
{
"$ref": "#/components/schemas/BaseReferralServiceRequest"
},
{
"required": [
"name",
"type"
]
}
]
},
"UpdateReferralServiceRequest": {
"title": "Update Referral Service Request",
"description": "Request body for updating an existing referral service. All fields are optional.",
"allOf": [
{
"$ref": "#/components/schemas/BaseReferralServiceRequest"
}
]
},
"StoreCustomIntakeRequest": {
"required": [
"name",
"type",
"apply_to",
"field_requirement"
],
"properties": {
"name": {
"description": "Field name. Must be unique within the business/location/station context.",
"type": "string",
"maxLength": 255,
"example": "Emergency Contact"
},
"subtitle": {
"type": "string",
"maxLength": 255,
"nullable": true
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
],
"example": "text"
},
"apply_to": {
"type": "string",
"enum": [
"all",
"waitlist_only",
"schedule_only"
],
"nullable": false
},
"field_requirement": {
"type": "string",
"enum": [
"no",
"yes",
"conditional"
],
"example": "yes"
},
"allow_multiple": {
"type": "boolean",
"example": false
},
"long_text": {
"type": "boolean",
"example": false
},
"numeric_unit_title": {
"type": "string",
"maxLength": 255,
"nullable": true
},
"info_text_value": {
"type": "string",
"nullable": true
},
"approved_formats": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"nullable": true
},
"image": {
"type": "string",
"maxLength": 255,
"nullable": true
},
"order": {
"type": "integer",
"minimum": 0,
"example": 1
},
"is_visible": {
"type": "boolean",
"example": true
},
"is_business_specific": {
"description": "Whether this intake is specific to the business/organization level",
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"required": [
"label"
],
"properties": {
"id": {
"type": "integer",
"nullable": true
},
"label": {
"type": "string",
"maxLength": 255
},
"order": {
"type": "integer",
"minimum": 0,
"nullable": true
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
},
"StoreFormRequestRequest": {
"required": [
"form_id"
],
"properties": {
"form_id": {
"description": "The UUID of the form. Must exist in the forms table and belong to the current business.",
"type": "string"
},
"client_ids": {
"description": "Array of client IDs to send the form request to. Required if request_id is not provided.",
"type": "array",
"items": {
"description": "Client ID. Must exist in the clients table and belong to the current business.",
"type": "integer"
},
"nullable": true
},
"request_id": {
"description": "UUID of an existing form request client. Required if client_ids is not provided. Used to attach client and providers to the new form request.",
"type": "string",
"format": "uuid",
"nullable": true
},
"message": {
"description": "Optional message to include with the form request.",
"type": "string",
"nullable": true
},
"send_email": {
"description": "Whether to send the form request via email.",
"type": "boolean",
"nullable": true
},
"send_sms": {
"description": "Whether to send the form request via SMS.",
"type": "boolean",
"nullable": true
},
"expire_option": {
"description": "How the form request should expire. Allowed values: never, duration, specific_date.",
"type": "string",
"enum": [
"never",
"duration",
"specific_date"
],
"nullable": true
},
"expire_duration": {
"description": "Number of units until expiration. Required if expire_option is 'duration'. Must be at least 1.",
"type": "integer",
"minimum": 1,
"nullable": true
},
"expire_duration_unit": {
"description": "Unit for expire_duration. Required if expire_option is 'duration'. Allowed values: days, hours, weeks, months.",
"type": "string",
"enum": [
"days",
"hours",
"weeks",
"months"
],
"nullable": true
},
"expire_date": {
"description": "Specific expiration date. Required if expire_option is 'specific_date'. Must be today or in the future.",
"type": "string",
"format": "date",
"nullable": true
},
"location_id": {
"description": "Optional location ID to specify which location this form request is for.",
"type": "integer",
"nullable": true
},
"station_id": {
"description": "Optional station ID to specify which station this form request is for.",
"type": "integer",
"nullable": true
}
},
"type": "object"
},
"UpdateClientAttributeRequest": {
"description": "Request for updating an existing client attribute",
"required": [
"id"
],
"properties": {
"id": {
"description": "Attribute ID to update",
"type": "integer",
"example": 1
},
"label": {
"description": "Display label for the attribute",
"type": "string",
"maxLength": 255,
"example": "Allergies"
},
"type": {
"description": "Attribute type",
"type": "string",
"enum": [
"text",
"number",
"date",
"select",
"boolean",
"email",
"phone",
"attachment"
],
"example": "text"
},
"options": {
"description": "Options for select/dropdown types",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Option ID for existing options",
"type": "integer",
"nullable": true
},
"label": {
"description": "Option label",
"type": "string",
"example": "Peanut"
},
"order": {
"description": "Display order",
"type": "integer",
"example": 1
}
},
"type": "object"
},
"nullable": true
},
"is_required": {
"description": "Whether the attribute is required",
"type": "boolean",
"example": false
},
"is_validator": {
"description": "Whether the attribute is used for validation",
"type": "boolean",
"example": false
},
"import_column_name": {
"description": "Column name for import mapping",
"type": "string",
"maxLength": 255,
"example": "allergies",
"nullable": true
}
},
"type": "object",
"example": {
"id": 1,
"label": "Allergies",
"type": "select",
"options": [
{
"id": 1,
"label": "Peanut",
"order": 1
},
{
"label": "Dairy",
"order": 2
}
],
"is_required": true,
"is_validator": false,
"import_column_name": "allergies"
}
},
"UpdateCustomIntakeRequest": {
"properties": {
"name": {
"description": "Field name. Must be unique within the business/location/station context.",
"type": "string",
"maxLength": 255,
"example": "Updated Field Name"
},
"subtitle": {
"type": "string",
"maxLength": 255,
"nullable": true
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
]
},
"apply_to": {
"type": "string",
"enum": [
"all",
"customer",
"staff",
"product",
"service"
]
},
"field_requirement": {
"type": "string",
"enum": [
"no",
"yes",
"conditional"
]
},
"allow_multiple": {
"type": "boolean",
"example": false
},
"long_text": {
"type": "boolean",
"example": false
},
"numeric_unit_title": {
"type": "string",
"maxLength": 255,
"nullable": true
},
"info_text_value": {
"type": "string",
"nullable": true
},
"approved_formats": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"nullable": true
},
"image": {
"type": "string",
"maxLength": 255,
"nullable": true
},
"order": {
"type": "integer",
"minimum": 0,
"example": 1
},
"is_visible": {
"type": "boolean",
"example": true
},
"is_business_specific": {
"description": "Whether this intake is specific to the business/organization level",
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"required": [
"label"
],
"properties": {
"id": {
"type": "integer",
"nullable": true
},
"label": {
"type": "string",
"maxLength": 255
},
"order": {
"type": "integer",
"minimum": 0,
"nullable": true
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
},
"AutomationExecutionHistoryResource": {
"description": "Automation execution history item",
"properties": {
"id": {
"description": "Execution record ID",
"type": "integer",
"example": 1
},
"patient_name": {
"description": "Patient name",
"type": "string",
"example": "John Doe"
},
"patient_email": {
"description": "Patient email",
"type": "string",
"example": "john.doe@example.com"
},
"action": {
"description": "Action performed",
"type": "string",
"example": "Appointment Schedule"
},
"run_time": {
"description": "ISO 8601 timestamp of when the action was executed (UTC). Frontend should convert to user's local timezone.",
"type": "string",
"format": "date-time",
"example": "2023-05-15T08:00:00+00:00"
},
"status": {
"description": "Execution status (Successful/Failed)",
"type": "string",
"example": "Successful"
},
"execution_duration": {
"description": "Execution duration in milliseconds",
"type": "integer",
"example": 1500
},
"error_message": {
"description": "Error message if failed",
"type": "string",
"example": ""
}
},
"type": "object"
},
"BusinessSimpleClientResource": {
"properties": {
"id": {
"type": "integer",
"example": 22
},
"first_name": {
"type": "string",
"example": "Taylor"
},
"last_name": {
"type": "string",
"example": "Lee"
},
"full_name": {
"type": "string",
"example": "Taylor Lee"
},
"email": {
"type": "string",
"example": "taylor@example.com"
},
"phone_number": {
"type": "string",
"example": "+1-555-0103",
"nullable": true
},
"profile_picture_url": {
"type": "string",
"example": "https://cdn.example.com/client.png",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true,
"nullable": true
},
"last_visit": {
"type": "string",
"format": "date-time",
"example": "2025-01-15T10:00:00Z",
"nullable": true
},
"priority": {
"type": "string",
"example": "high",
"nullable": true
},
"external_id": {
"type": "string",
"example": "EXT-123",
"nullable": true
},
"attribute_values": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"value": {
"type": "string",
"example": "Yes"
},
"attribute": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"key": {
"type": "string",
"example": "allergies"
},
"name": {
"type": "string",
"example": "Allergies"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
},
"BusinessSimpleLocationResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Downtown Clinic"
},
"address": {
"type": "string",
"example": "123 Main St",
"nullable": true
},
"country": {
"type": "string",
"example": "US",
"nullable": true
},
"state": {
"type": "string",
"example": "CA",
"nullable": true
},
"city": {
"type": "string",
"example": "Los Angeles",
"nullable": true
},
"image": {
"type": "string",
"example": "https://cdn.example.com/location.png",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true,
"nullable": true
},
"phone_number": {
"type": "string",
"example": "+1-555-0100",
"nullable": true
},
"description": {
"type": "string",
"example": "Primary location",
"nullable": true
},
"stations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BasicProviderResource"
}
}
},
"type": "object"
},
"BasicProviderResource": {
"required": [
"id",
"name",
"station_id",
"location_id"
],
"properties": {
"id": {
"description": "LocationStation ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Provider name",
"type": "string",
"example": "Dr. John Smith"
},
"station_id": {
"description": "Station ID",
"type": "integer",
"example": 5
},
"location_id": {
"description": "Location ID",
"type": "integer",
"example": 3
}
},
"type": "object"
},
"BusinessSimpleServiceResource": {
"properties": {
"id": {
"type": "integer",
"example": 15
},
"name": {
"type": "string",
"example": "General Consultation"
},
"referral_type": {
"type": "string",
"example": "incoming",
"nullable": true
},
"description": {
"type": "string",
"example": "Initial consultation",
"nullable": true
},
"time_in_minute": {
"type": "integer",
"example": 30,
"nullable": true
},
"is_available": {
"type": "boolean",
"example": true,
"nullable": true
},
"auto_approve": {
"type": "boolean",
"example": false,
"nullable": true
},
"is_visible": {
"type": "boolean",
"example": true,
"nullable": true
},
"appointment_methods": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "In person"
}
},
"type": "object"
}
}
},
"type": "object"
},
"BusinessSimpleUserResource": {
"properties": {
"id": {
"type": "integer",
"example": 8
},
"first_name": {
"type": "string",
"example": "Alex"
},
"last_name": {
"type": "string",
"example": "Johnson"
},
"full_name": {
"type": "string",
"example": "Alex Johnson"
},
"email": {
"type": "string",
"example": "alex@example.com"
},
"phone_number": {
"type": "string",
"example": "+1-555-0102",
"nullable": true
},
"profile_picture": {
"type": "string",
"example": "https://cdn.example.com/user.png",
"nullable": true
},
"role": {
"type": "string",
"example": "Admin",
"nullable": true
}
},
"type": "object"
},
"BasicClientResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"external_id": {
"type": "string",
"example": "123456"
},
"first_name": {
"type": "string",
"example": "Alice"
},
"last_name": {
"type": "string",
"example": "Smith"
},
"full_name": {
"type": "string",
"example": "Alice Smith"
},
"email": {
"type": "string",
"example": "alice@example.com"
},
"phone_number": {
"type": "string",
"example": "1234567890"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/pic.jpg"
},
"is_active": {
"type": "boolean",
"example": true
},
"last_visit": {
"type": "string",
"format": "date-time",
"example": "2024-07-01T12:00:00Z"
},
"emr_sync_status": {
"type": "string",
"example": "synched"
}
},
"type": "object"
},
"DetailedClientResource": {
"allOf": [
{
"$ref": "#/components/schemas/BasicClientResource"
},
{
"properties": {
"attributes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientAttributeResource"
}
},
"attribute_values": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"categories": {
"description": "Client categories (only included when requested via include=categories)",
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientCategoryResource"
}
}
},
"type": "object"
}
]
},
"AttributeResourceCategoryCondition": {
"description": "Client attribute with category condition operators",
"required": [
"id",
"label",
"type",
"operators"
],
"properties": {
"id": {
"description": "Attribute ID",
"type": "integer",
"example": 1
},
"label": {
"description": "Attribute display label",
"type": "string",
"example": "Allergies"
},
"type": {
"description": "Attribute type",
"type": "string",
"example": "text"
},
"operators": {
"description": "Available operators for this attribute type",
"type": "array",
"items": {
"properties": {
"key": {
"description": "Operator key",
"type": "string",
"example": "equals"
},
"label": {
"description": "Operator display label",
"type": "string",
"example": "Equals"
},
"value_type": {
"description": "Expected value type for this operator",
"type": "string",
"example": "string"
}
},
"type": "object"
}
},
"options": {
"description": "Available options for select/dropdown types",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Peanut"
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
},
"BasicClientAttributeResource": {
"required": [
"id",
"key",
"label",
"type",
"is_required",
"is_validator",
"is_system_field"
],
"properties": {
"id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "allergies"
},
"label": {
"type": "string",
"example": "Allergies"
},
"type": {
"type": "string",
"example": "text"
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "peanut"
},
"value": {
"type": "string",
"example": "Peanut"
},
"label": {
"type": "string",
"example": "Peanut"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"nullable": true
},
"is_required": {
"type": "boolean",
"example": false
},
"is_validator": {
"type": "boolean",
"example": false
},
"is_system_field": {
"type": "boolean",
"example": false
},
"import_column_name": {
"type": "string",
"example": "Allergies",
"nullable": true
}
},
"type": "object"
},
"ClientAttributeCollection": {
"description": "Paginated collection of client attributes",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientAttributeResource"
}
},
"pagination": {
"properties": {
"total": {
"description": "Total number of records",
"type": "integer",
"example": 100
},
"count": {
"description": "Number of records in current page",
"type": "integer",
"example": 15
},
"per_page": {
"description": "Number of records per page",
"type": "integer",
"example": 15
},
"current_page": {
"description": "Current page number",
"type": "integer",
"example": 1
},
"total_pages": {
"description": "Total number of pages",
"type": "integer",
"example": 7
}
},
"type": "object"
}
},
"type": "object"
},
"ClientAttributeForClientImportResource": {
"required": [
"id",
"label",
"type",
"is_system_field",
"import_column_name"
],
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "First Name"
},
"key": {
"type": "string",
"example": "first_name"
},
"type": {
"type": "string",
"example": "text"
},
"is_required": {
"type": "boolean",
"example": false
},
"is_validator": {
"type": "boolean",
"example": false
},
"is_system_field": {
"type": "boolean",
"example": false
},
"import_column_name": {
"type": "string",
"example": "first_name"
}
},
"type": "object"
},
"ClientAttributeForPatientSettingResource": {
"required": [
"id",
"label",
"type",
"is_required",
"is_validator",
"is_system_field",
"is_emr_field"
],
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Allergies"
},
"type": {
"type": "string",
"example": "text"
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"label": {
"type": "string",
"example": "Peanut"
}
},
"type": "object"
},
"nullable": true
},
"is_required": {
"type": "boolean",
"example": false
},
"is_validator": {
"type": "boolean",
"example": false
},
"is_system_field": {
"type": "boolean",
"example": false
},
"is_emr_field": {
"type": "boolean",
"example": false
}
},
"type": "object"
},
"ClientAttributeResource": {
"required": [
"id",
"key",
"label",
"type",
"is_required",
"is_validator",
"is_system_field"
],
"properties": {
"id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "allergies"
},
"label": {
"type": "string",
"example": "Allergies"
},
"type": {
"type": "string",
"example": "text"
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "peanut"
},
"value": {
"type": "string",
"example": "Peanut"
},
"label": {
"type": "string",
"example": "Peanut"
},
"order": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"nullable": true
},
"is_required": {
"type": "boolean",
"example": false
},
"is_validator": {
"type": "boolean",
"example": false
},
"is_system_field": {
"type": "boolean",
"example": false
},
"import_column_name": {
"type": "string",
"example": "Allergies",
"nullable": true
}
},
"type": "object"
},
"BookingReferralResource": {
"description": "Booking referral payload for referral flow",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"example": "pending"
},
"score_map": {
"type": "object",
"nullable": true
},
"client_id": {
"type": "integer",
"example": 12
},
"business_id": {
"type": "integer",
"example": 5
},
"service_id": {
"type": "integer",
"example": 21
},
"form_id": {
"type": "string"
},
"form_response_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"selected_partner_id": {
"type": "integer",
"example": 9
},
"selected_partner": {
"oneOf": [
{
"$ref": "#/components/schemas/ClientBookingOrganizationResource"
}
],
"nullable": true
},
"location": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"image": {
"type": "string"
}
},
"type": "object",
"nullable": true
},
"provider": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"image": {
"type": "string"
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
},
"ClientBookingLocationResource": {
"description": "Client booking location resource",
"properties": {
"id": {
"description": "Location ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Location name",
"type": "string",
"example": "Main Clinic"
},
"description": {
"description": "Location description",
"type": "string",
"nullable": true
},
"email": {
"description": "Location email",
"type": "string",
"nullable": true
},
"phone_number": {
"description": "Location phone number",
"type": "string",
"nullable": true
},
"image": {
"description": "Location image URL",
"type": "string",
"nullable": true
},
"address": {
"description": "Location address",
"type": "string",
"nullable": true
},
"country": {
"description": "Location country",
"type": "string",
"nullable": true
},
"state": {
"description": "Location state",
"type": "string",
"nullable": true
},
"city": {
"description": "Location city",
"type": "string",
"nullable": true
},
"provider_count": {
"description": "Providers count",
"type": "integer",
"nullable": true
},
"service_count": {
"description": "Services count",
"type": "integer",
"nullable": true
},
"provider_id": {
"description": "Locationstation id when flow is stations",
"type": "integer",
"nullable": true
}
},
"type": "object"
},
"ClientBookingOrganizationResource": {
"description": "Client booking organization resource",
"properties": {
"id": {
"description": "Organization ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Organization name",
"type": "string",
"example": "Migranium Health"
},
"description": {
"description": "Organization description",
"type": "string",
"nullable": true
},
"email": {
"description": "Organization email",
"type": "string",
"nullable": true
},
"phone_number": {
"description": "Organization phone number",
"type": "string",
"nullable": true
},
"image": {
"description": "Organization image URL",
"type": "string",
"nullable": true
},
"address": {
"description": "Organization address",
"type": "string",
"nullable": true
},
"country": {
"description": "Organization country",
"type": "string",
"nullable": true
},
"state": {
"description": "Organization state",
"type": "string",
"nullable": true
},
"city": {
"description": "Organization city",
"type": "string",
"nullable": true
}
},
"type": "object"
},
"ClientBookingProviderResource": {
"description": "Client booking provider (station) resource",
"properties": {
"id": {
"description": "Location station ID",
"type": "integer",
"example": 10
},
"station_id": {
"description": "Station ID",
"type": "integer",
"example": 5
},
"location_id": {
"description": "Location ID",
"type": "integer",
"example": 2
},
"name": {
"description": "Provider name",
"type": "string",
"example": "Dr. Smith"
},
"description": {
"description": "Provider description",
"type": "string",
"nullable": true
},
"email": {
"description": "Provider email",
"type": "string",
"nullable": true
},
"phone_number": {
"description": "Provider phone number",
"type": "string",
"nullable": true
},
"image": {
"description": "Provider image URL",
"type": "string",
"nullable": true
},
"time_in_minute": {
"description": "Service duration override",
"type": "integer",
"nullable": true
},
"location": {
"$ref": "#/components/schemas/ClientBookingLocationResource"
}
},
"type": "object"
},
"ClientBookingServiceResource": {
"description": "Client booking service resource",
"properties": {
"id": {
"description": "Service ID",
"type": "integer",
"example": 7
},
"name": {
"description": "Service name",
"type": "string",
"example": "Consultation"
},
"description": {
"description": "Service description",
"type": "string",
"nullable": true
},
"time_in_minute": {
"description": "Service duration",
"type": "integer",
"example": 30
},
"has_referral": {
"description": "Requires referral form",
"type": "boolean",
"nullable": true
},
"appointment_methods": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
},
"ClientBookingStationResource": {
"description": "Client booking station resource",
"properties": {
"id": {
"description": "Station ID",
"type": "integer",
"example": 5
},
"name": {
"description": "Station name",
"type": "string",
"example": "Station A"
},
"description": {
"description": "Station description",
"type": "string",
"nullable": true
},
"email": {
"description": "Station email",
"type": "string",
"nullable": true
},
"phone_number": {
"description": "Station phone number",
"type": "string",
"nullable": true
},
"image": {
"description": "Station image URL",
"type": "string",
"nullable": true
}
},
"type": "object"
},
"PeClientBookingResource": {
"description": "Client booking details for schedule or walk-in. Walk-in includes queue info.",
"properties": {
"booking_id": {
"type": "string",
"example": "BKW-12345"
},
"booking_type": {
"type": "string",
"example": "walk_in"
},
"client_id": {
"type": "integer",
"example": 12
},
"service_id": {
"type": "integer",
"example": 7
},
"location_station_id": {
"type": "integer",
"example": 18
},
"status": {
"type": "string",
"example": "pending"
},
"custom_schedule_link_id": {
"type": "integer",
"example": 3,
"nullable": true
},
"made_by": {
"type": "string",
"example": "client",
"nullable": true
},
"form_response_id": {
"type": "integer",
"example": 44,
"nullable": true
},
"feedback_form_id": {
"type": "integer",
"example": 11,
"nullable": true
},
"status_updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"booking_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"booking_reference": {
"type": "string",
"nullable": true
},
"check_in_status": {
"type": "string",
"nullable": true
},
"cancelled_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelled_by": {
"type": "string",
"nullable": true
},
"cancellation_reason": {
"type": "string",
"nullable": true
},
"joined_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"address": {
"type": "string",
"nullable": true
},
"type": {
"description": "Effective appointment method label",
"type": "string",
"nullable": true
},
"station": {
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Dr. Smith"
},
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "string",
"nullable": true
},
"location_id": {
"type": "integer",
"example": 2
},
"location_station_id": {
"type": "integer",
"example": 18
},
"service_duration": {
"type": "integer",
"example": 30
},
"banners": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
},
"location": {
"properties": {
"id": {
"type": "integer",
"example": 2
},
"name": {
"type": "string",
"example": "Main Clinic"
}
},
"type": "object"
},
"service": {
"properties": {
"id": {
"type": "integer",
"example": 7
},
"name": {
"type": "string",
"example": "Consultation"
}
},
"type": "object"
},
"client": {
"properties": {
"id": {
"type": "integer",
"example": 12
},
"full_name": {
"type": "string",
"example": "Jane Doe"
},
"phone_number": {
"type": "string",
"example": "+1234567890"
},
"email": {
"type": "string",
"example": "jane@example.com"
}
},
"type": "object"
},
"position": {
"description": "Queue position (walk-in only)",
"type": "integer",
"example": 4,
"nullable": true
},
"estimated_wait_time_in_minutes": {
"description": "Queue wait time (walk-in only)",
"type": "integer",
"example": 30,
"nullable": true
}
},
"type": "object"
},
"ClientCategoryDetailResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "VIP Clients"
},
"description": {
"type": "string",
"example": "High-value clients",
"nullable": true
},
"color": {
"type": "string",
"example": "#FF5733"
},
"type": {
"type": "string",
"enum": [
"manual",
"conditional"
],
"example": "conditional"
},
"business_id": {
"type": "integer",
"example": 1
},
"conditions": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"condition_type": {
"type": "string",
"enum": [
"priority",
"registration_date",
"last_visit",
"information_check"
],
"example": "priority"
},
"operator": {
"type": "string",
"example": "equals"
},
"conditional_value": {
"type": "string",
"example": "high"
},
"date_range_start": {
"type": "string",
"format": "date",
"nullable": true
},
"date_range_end": {
"type": "string",
"format": "date",
"nullable": true
},
"information_type": {
"type": "string",
"enum": [
"form_answer",
"custom_intake_answer"
],
"nullable": true
},
"form_question_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"custom_intake_id": {
"type": "integer",
"nullable": true
}
},
"type": "object"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"ClientCategoryResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "VIP Clients"
},
"description": {
"type": "string",
"example": "High-value clients",
"nullable": true
},
"color": {
"type": "string",
"example": "#FF5733"
},
"type": {
"type": "string",
"enum": [
"manual",
"conditional"
],
"example": "conditional"
},
"business_id": {
"type": "integer",
"example": 1
},
"conditions": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"condition_type": {
"type": "string",
"enum": [
"priority",
"registration_date",
"last_visit",
"information_check"
],
"example": "priority"
},
"operator": {
"type": "string",
"example": "equals"
},
"conditional_value": {
"type": "string",
"example": "high"
},
"date_range_start": {
"type": "string",
"format": "date",
"nullable": true
},
"date_range_end": {
"type": "string",
"format": "date",
"nullable": true
},
"information_type": {
"type": "string",
"enum": [
"form_answer",
"custom_intake_answer"
],
"nullable": true
},
"form_question_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"custom_intake_id": {
"type": "integer",
"nullable": true
}
},
"type": "object"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
}
},
"type": "object"
},
"CustomIntakeForConditional": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Preferred Contact Method"
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
]
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": "1"
},
"label": {
"type": "string",
"example": "Email"
}
},
"type": "object"
}
}
},
"type": "object"
},
"FormFieldResponseForCategory": {
"properties": {
"form_id": {
"type": "string",
"example": "a1b2c3d4-e5f6-7890"
},
"question": {
"type": "string",
"example": "What is your name?"
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
]
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "opt1"
},
"label": {
"type": "string",
"example": "Option 1"
}
},
"type": "object"
}
}
},
"type": "object"
},
"FormForConditional": {
"properties": {
"form_id": {
"type": "string",
"example": "a1b2c3d4-e5f6-7890"
},
"form_title": {
"type": "string",
"example": "Client Intake Form"
},
"questions": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890"
},
"question": {
"type": "string",
"example": "What is your name?"
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
],
"example": "text"
},
"options": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "opt1"
},
"label": {
"type": "string",
"example": "Option 1"
}
},
"type": "object"
},
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
},
"ClientIntakeResponseResource": {
"required": [
"custom_intake_id",
"client_id",
"value"
],
"properties": {
"id": {
"description": "The unique identifier of the custom intake response",
"type": "integer"
},
"custom_intake_id": {
"description": "The ID of the associated custom intake field",
"type": "integer"
},
"client_id": {
"description": "The ID of the client who provided the response",
"type": "integer"
},
"value": {
"description": "The response value provided by the client",
"type": "string"
},
"value_label": {
"description": "Human-readable label for the value (option labels if options exist, otherwise the value itself)",
"type": "string"
},
"created_at": {
"description": "When the response was created",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "When the response was last updated",
"type": "string",
"format": "date-time"
},
"field": {
"$ref": "#/components/schemas/CustomIntakeForConditional"
},
"selected_options": {
"description": "Selected options if this is a multi-select field",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomIntakeOptionResource"
}
}
},
"type": "object"
},
"CustomIntakeOptionResource": {
"required": [
"label"
],
"properties": {
"id": {
"description": "The unique identifier of the custom intake option",
"type": "integer",
"nullable": true
},
"label": {
"description": "The display label for the option",
"type": "string",
"maxLength": 255
},
"custom_intake_id": {
"description": "The ID of the associated custom intake",
"type": "integer",
"nullable": true
}
},
"type": "object"
},
"CustomIntakeResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"key": {
"type": "string",
"example": "emergency_contact"
},
"name": {
"type": "string",
"example": "Emergency Contact"
},
"subtitle": {
"type": "string",
"example": "Who to contact in case of emergency",
"nullable": true
},
"type": {
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
],
"example": "text"
},
"apply_to": {
"type": "string",
"enum": [
"all",
"customer",
"staff",
"product",
"service"
],
"example": "all"
},
"field_requirement": {
"type": "string",
"enum": [
"no",
"yes",
"conditional"
],
"example": "yes"
},
"allow_multiple": {
"type": "boolean",
"example": false
},
"long_text": {
"type": "boolean",
"example": false
},
"numeric_unit_title": {
"type": "string",
"example": "kg",
"nullable": true
},
"info_text_value": {
"type": "string",
"example": "Additional information",
"nullable": true
},
"approved_formats": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"pdf",
"jpg"
]
},
"image": {
"type": "string",
"example": "path/to/image.jpg",
"nullable": true
},
"order": {
"type": "integer",
"example": 1
},
"is_visible": {
"type": "boolean",
"example": true
},
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomIntakeOptionResource"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"FeedbackDetailResource": {
"description": "Detailed feedback including general feedback and field responses",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/FeedbackSummary"
},
{
"properties": {
"general_feedback": {
"description": "General feedback provided by the patient",
"type": "string",
"example": "The service was excellent!",
"nullable": true
},
"responses": {
"description": "Detailed responses for each form field",
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldResponse"
}
}
},
"type": "object"
}
]
},
"FieldResponseForFeedback": {
"description": "Detailed response for a specific form field",
"properties": {
"field_id": {
"description": "ID of the form field",
"type": "integer",
"example": 1
},
"question": {
"description": "The question text from the form field",
"type": "string",
"example": "How was your experience?"
},
"type": {
"description": "Internal field type identifier",
"type": "string",
"enum": [
"text",
"rating",
"dropdown",
"checkbox",
"radio",
"scale",
"boolean"
],
"example": "rating"
},
"display_type": {
"description": "Human-readable field type for display",
"type": "string",
"example": "Rating Scale"
},
"raw_value": {
"description": "Original response value as stored",
"type": "string",
"example": "5"
},
"formatted_value": {
"description": "Processed/display-friendly version of the response",
"type": "string",
"example": "5 stars"
},
"value_type": {
"description": "Data type of the response value",
"type": "string",
"enum": [
"string",
"integer",
"float",
"boolean",
"array"
],
"example": "integer"
}
},
"type": "object"
},
"Feedback": {
"description": "Basic feedback summary information",
"properties": {
"id": {
"description": "Unique identifier for the feedback response",
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"patient_name": {
"description": "Full name of the patient providing feedback",
"type": "string",
"example": "John Doe"
},
"patient_avatar": {
"description": "URL to the patient's profile picture",
"type": "string",
"format": "uri",
"example": "https://example.com/avatars/john-doe.jpg",
"nullable": true
},
"station_name": {
"description": "Name of the station where service was provided",
"type": "string",
"example": "Main Station",
"nullable": true
},
"location_name": {
"description": "Name of the location where service was provided",
"type": "string",
"example": "Downtown Clinic",
"nullable": true
},
"service_name": {
"description": "Name of the service received",
"type": "string",
"example": "Dental Checkup",
"nullable": true
},
"rating": {
"description": "Numerical rating provided (1-5 scale)",
"type": "integer",
"maximum": 5,
"minimum": 1,
"example": 5,
"nullable": true
},
"date": {
"description": "When the feedback was submitted",
"type": "string",
"format": "date-time",
"example": "2023-01-01T12:00:00Z"
}
},
"type": "object"
},
"FeedbackSummaryDetail": {
"description": "Detailed feedback summary including response distribution",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/FeedbackSummary"
},
{
"properties": {
"ui_view": {
"description": "UI View",
"type": "string",
"enum": [
"list",
"pie",
"bar"
],
"example": "bar"
},
"responses": {
"description": "Response data format depends on field type (has_options in config)",
"type": "object",
"oneOf": [
{
"description": "For option-based fields (dropdown, radio, checkbox, satisfaction_scale, etc.)",
"properties": {
"responses": {
"type": "object",
"example": {
"Very Unsatisfied": 0,
"Unsatisfied": 0,
"Neutral": 2,
"Satisfied": 1,
"Very Satisfied": 0
},
"additionalProperties": {
"type": "integer",
"example": 2
}
}
},
"type": "object"
},
{
"description": "For non-option fields (text, long_text, number, etc.)",
"properties": {
"responses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldResponse"
}
}
},
"type": "object"
}
]
}
},
"type": "object"
}
]
},
"FeedbackSummary": {
"description": "Summary of a feedback question with response count",
"properties": {
"question_id": {
"description": "Unique identifier for the question",
"type": "string",
"format": "uuid",
"example": "33acc6fe-cc21-4e5b-b2d4-05d66844d9d5"
},
"question": {
"description": "The question text",
"type": "string",
"example": "How satisfied are you with our service?"
},
"type_label": {
"description": "Human-readable label for the field type from field_types config",
"type": "string",
"example": "Satisfaction Scale"
},
"type": {
"description": "Field type identifier matching config/field_types.php keys",
"type": "string",
"example": "satisfaction_scale"
},
"station_name": {
"description": "Name of the station where service was provided",
"type": "string",
"example": "Main Station",
"nullable": true
},
"location_name": {
"description": "Name of the location where service was provided",
"type": "string",
"example": "Downtown Clinic",
"nullable": true
},
"service_name": {
"description": "Name of the service received",
"type": "string",
"example": "Dental Checkup",
"nullable": true
},
"total_response_count": {
"description": "Total number of responses for this question",
"type": "integer",
"example": 3
}
},
"type": "object"
},
"FieldResponse": {
"properties": {
"field_id": {
"type": "integer",
"example": 1
},
"question": {
"type": "string",
"example": "How was your experience?"
},
"type": {
"type": "string",
"example": "rating"
},
"display_type": {
"type": "string",
"example": "Rating Scale"
},
"raw_value": {
"type": "string",
"example": "5"
},
"formatted_value": {
"type": "string",
"example": "5"
},
"value_type": {
"type": "string",
"example": "integer"
}
},
"type": "object"
},
"ClientFormResponseResource": {
"description": "Client form response",
"properties": {
"response_uuid": {
"description": "The UUID of the form response",
"type": "string",
"example": "b7e6c2e2-1f2a-4c3d-9e2a-123456789abc"
},
"form_name": {
"description": "The name of the form",
"type": "string",
"example": "Customer Feedback"
},
"service_name": {
"description": "The service name",
"type": "string",
"example": "Premium Support",
"nullable": true
},
"station_name": {
"description": "The station name",
"type": "string",
"example": "Station A",
"nullable": true
},
"submitted_at": {
"description": "Submission timestamp in ISO8601 format",
"type": "string",
"format": "date-time",
"example": "2024-06-01T12:34:56.000000Z"
}
},
"type": "object"
},
"FormRequestClientDetail": {
"properties": {
"id": {
"description": "Form request client UUID",
"type": "string"
},
"client_id": {
"description": "Client id",
"type": "integer"
},
"client_name": {
"description": "Client full name",
"type": "string"
},
"is_completed": {
"description": "Whether the client has completed the form",
"type": "boolean"
},
"is_email_sent": {
"description": "Whether the email was sent to the client",
"type": "boolean"
},
"is_sms_sent": {
"description": "Whether the SMS was sent to the client",
"type": "boolean"
},
"frontend_url": {
"description": "Frontend URL for this client's form request",
"type": "string"
},
"created_at": {
"description": "Creation timestamp",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"FormRequestClient": {
"properties": {
"id": {
"description": "Form request client UUID",
"type": "string"
},
"client_id": {
"description": "Client id",
"type": "integer"
},
"client_name": {
"description": "Client full name",
"type": "string"
},
"is_completed": {
"description": "Whether the client has completed the form",
"type": "boolean"
},
"is_email_sent": {
"description": "Whether the email was sent to the client",
"type": "boolean"
},
"is_sms_sent": {
"description": "Whether the SMS was sent to the client",
"type": "boolean"
},
"frontend_url": {
"description": "Frontend URL for this client's form request",
"type": "string"
}
},
"type": "object"
},
"FormRequest": {
"properties": {
"id": {
"description": "Form request UUID",
"type": "string"
},
"form_id": {
"description": "UUID of the associated form",
"type": "string"
},
"expire_option": {
"description": "Expiration option (never, duration, specific_date)",
"type": "string"
},
"expire_duration": {
"description": "Duration until expiration",
"type": "integer",
"nullable": true
},
"expire_duration_unit": {
"description": "Unit for expiration duration (days, hours, weeks, months)",
"type": "string",
"nullable": true
},
"expire_date": {
"description": "Specific expiration date",
"type": "string",
"format": "date",
"nullable": true
},
"message": {
"description": "Message sent with the form request",
"type": "string",
"nullable": true
},
"send_email": {
"description": "Whether to send email notifications",
"type": "boolean"
},
"send_sms": {
"description": "Whether to send SMS notifications",
"type": "boolean"
},
"clients": {
"description": "List of clients associated with this form request",
"type": "array",
"items": {
"$ref": "#/components/schemas/FormRequestClient"
}
},
"is_completed": {
"description": "Whether all clients have completed the form",
"type": "boolean"
},
"is_expired": {
"description": "Whether the form request is expired",
"type": "boolean"
},
"created_at": {
"description": "Creation timestamp",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"FormResponseResource": {
"properties": {
"id": {
"description": "Form response UUID",
"type": "string",
"format": "uuid"
},
"status": {
"description": "Response status",
"type": "string"
},
"submitted_at": {
"description": "Submission timestamp",
"type": "string",
"format": "date-time"
},
"created_at": {
"description": "Creation timestamp",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Update timestamp",
"type": "string",
"format": "date-time"
},
"form": {
"$ref": "#/components/schemas/FormSummaryResource"
},
"client": {
"description": "Client information",
"type": "object"
},
"location": {
"description": "Location information",
"type": "object"
},
"station": {
"description": "Station information",
"type": "object"
},
"responses": {
"description": "Field responses",
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
},
"FormSummaryResource": {
"properties": {
"id": {
"description": "Form UUID",
"type": "string",
"format": "uuid"
},
"title": {
"description": "Form title",
"type": "string"
},
"type": {
"description": "Form type",
"type": "string"
},
"description": {
"description": "Form description",
"type": "string"
}
},
"type": "object"
},
"IntakeDetailResource": {
"required": [
"id",
"name",
"type",
"apply_to",
"field_requirement",
"allow_multiple",
"long_text",
"is_visible"
],
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/IntakeResourceForList"
},
{
"properties": {
"field_requirement": {
"description": "Whether the field is required",
"type": "string",
"enum": [
"no",
"yes",
"conditional"
],
"example": "yes"
},
"allow_multiple": {
"description": "Whether multiple values are allowed",
"type": "boolean",
"example": false
},
"long_text": {
"description": "Whether this is a long text field",
"type": "boolean",
"example": false
},
"numeric_unit_title": {
"description": "Unit title for numeric fields",
"type": "string",
"example": "kg",
"nullable": true
},
"info_text_value": {
"description": "Additional informational text",
"type": "string",
"example": "Additional information",
"nullable": true
},
"approved_formats": {
"description": "Approved file formats for attachment fields",
"type": "array",
"items": {
"type": "string",
"example": "pdf"
},
"nullable": true
},
"image": {
"description": "Path to associated image",
"type": "string",
"example": "path/to/image.jpg",
"nullable": true
},
"is_visible": {
"description": "Whether the field is visible",
"type": "boolean",
"example": true
},
"options": {
"description": "Available options for dropdown/radio/checkbox fields",
"type": "array",
"items": {
"$ref": "#/components/schemas/IntakeOptionResource"
}
}
},
"type": "object"
}
]
},
"IntakeOptionResource": {
"required": [
"label"
],
"properties": {
"id": {
"description": "The unique identifier of the custom intake option",
"type": "integer",
"nullable": true
},
"label": {
"description": "The display label for the option",
"type": "string",
"maxLength": 255
},
"custom_intake_id": {
"description": "The ID of the associated custom intake",
"type": "integer",
"nullable": true
}
},
"type": "object"
},
"IntakeResourceForList": {
"required": [
"id",
"name",
"type",
"apply_to"
],
"properties": {
"id": {
"description": "The unique identifier of the intake field",
"type": "integer",
"example": 1
},
"name": {
"description": "The display name of the intake field",
"type": "string",
"example": "Emergency Contact"
},
"subtitle": {
"description": "The subtitle or description of the intake field",
"type": "string",
"example": "Who to contact in case of emergency",
"nullable": true
},
"type": {
"description": "The type of the intake field",
"type": "string",
"enum": [
"text",
"long_text",
"number",
"dropdown",
"radio",
"checkbox",
"date",
"attachment",
"email",
"phone",
"info_text",
"info_image",
"boolean"
],
"example": "text"
},
"type_label": {
"description": "The human-readable label for the field type",
"type": "string",
"example": "Text Input"
},
"apply_labels": {
"description": "The human-readable label for what the field applies to",
"type": "string",
"example": "All"
},
"apply_to": {
"description": "What the intake field applies to",
"type": "string",
"enum": [
"all",
"customer",
"staff",
"product",
"service"
],
"example": "all"
},
"stations": {
"description": "List of stations this intake field is associated with",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Station"
}
},
"type": "object"
}
}
},
"type": "object"
},
"PatientExperienceSettingResource": {
"properties": {
"allow_profile_update": {
"description": "Allow patients to update their profile",
"type": "boolean",
"example": true
},
"allow_two_way_chatting": {
"description": "Allow two-way chatting between patients and providers",
"type": "boolean",
"example": false
},
"attribute_preferences": {
"description": "Array of attribute preferences",
"type": "array",
"items": {
"properties": {
"key": {
"description": "Attribute key",
"type": "string",
"example": "phone"
},
"label": {
"description": "Attribute label",
"type": "string",
"example": "Phone Number"
},
"type": {
"description": "Attribute type",
"type": "string",
"example": "string"
},
"is_required": {
"description": "Whether it's a system field",
"type": "boolean",
"example": true
},
"preference_id": {
"description": "ID of the attribute preference",
"type": "integer",
"example": 1
},
"is_allowed": {
"description": "Whether the attribute is allowed",
"type": "boolean",
"example": true
},
"attribute_id": {
"description": "ID of the client attribute",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
},
"PublicPatientExperienceSettingResource": {
"properties": {
"allow_profile_update": {
"description": "Allow patients to update their profile",
"type": "boolean",
"example": true
},
"allow_two_way_chatting": {
"description": "Allow two-way chatting between patients and providers",
"type": "boolean",
"example": false
},
"attribute_preferences": {
"description": "Array of attribute preferences",
"type": "array",
"items": {
"properties": {
"key": {
"description": "Attribute key",
"type": "string",
"example": "phone"
},
"label": {
"description": "Attribute label",
"type": "string",
"example": "Phone Number"
},
"type": {
"description": "Attribute type",
"type": "string",
"example": "string"
},
"is_required": {
"description": "Whether it's a system field",
"type": "boolean",
"example": true
},
"preference_id": {
"description": "ID of the attribute preference",
"type": "integer",
"example": 1
},
"is_allowed": {
"description": "Whether the attribute is allowed",
"type": "boolean",
"example": true
},
"attribute_id": {
"description": "ID of the client attribute",
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
},
"PatientFeedbackResponse": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"uuid": {
"type": "string",
"example": "abc123-xyz456"
},
"patient_name": {
"type": "string",
"example": "John Doe"
},
"patient_avatar": {
"type": "string",
"example": "https://example.com/avatar.jpg",
"nullable": true
},
"station": {
"type": "string",
"example": "Main Station",
"nullable": true
},
"location": {
"type": "string",
"example": "Downtown Clinic",
"nullable": true
},
"service": {
"type": "string",
"example": "Dental Checkup",
"nullable": true
},
"rating": {
"type": "integer",
"example": 5,
"nullable": true
},
"rating_stars": {
"properties": {
"filled": {
"type": "integer",
"example": 5
},
"total": {
"type": "integer",
"example": 5
},
"percentage": {
"type": "number",
"format": "float",
"example": 100
}
},
"type": "object"
},
"general_feedback": {
"type": "string",
"example": "Great service!",
"nullable": true
},
"submitted_at": {
"type": "string",
"format": "date-time",
"example": "2023-01-01T12:00:00Z"
},
"formatted_date": {
"type": "string",
"example": "01 Jan 2023, 12:00 PM"
},
"field_responses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldResponse"
}
}
},
"type": "object"
},
"PeSettingAttributePermissionResource": {
"required": [
"id",
"label",
"client_allowed_to_view",
"client_allowed_to_edit"
],
"properties": {
"id": {
"description": "Client attribute ID",
"type": "integer",
"example": 1
},
"label": {
"description": "Client attribute label",
"type": "string",
"example": "Date of Birth"
},
"client_allowed_to_view": {
"description": "Whether clients are allowed to view this attribute",
"type": "boolean",
"example": true
},
"client_allowed_to_edit": {
"description": "Whether clients are allowed to edit this attribute",
"type": "boolean",
"example": false
}
},
"type": "object"
},
"PeSettingResource": {
"required": [
"is_chat_enabled",
"allow_profile_update",
"allow_two_way_chatting",
"sign_up_options",
"allow_intake_view",
"allow_intake_edit",
"notification_enabled",
"sms_notification_enabled",
"email_notification_enabled",
"attribute_preferences"
],
"properties": {
"is_chat_enabled": {
"description": "Whether chat is enabled for patients",
"type": "boolean",
"example": true
},
"allow_profile_update": {
"description": "Whether patients are allowed to update their profile",
"type": "boolean",
"example": true
},
"allow_two_way_chatting": {
"description": "Whether two-way chatting is enabled",
"type": "boolean",
"example": true
},
"sign_up_options": {
"description": "Available sign-up options for patients. Possible values: email_password, phone_number_otp, gmail, microsoft, apple, custom_sso",
"type": "array",
"items": {
"type": "string",
"enum": [
"email_password",
"phone_number_otp",
"gmail",
"microsoft",
"apple",
"custom_sso"
]
},
"example": [
"email_password",
"gmail",
"microsoft"
]
},
"allow_intake_view": {
"description": "Whether patients are allowed to view intake forms",
"type": "boolean",
"example": true
},
"allow_intake_edit": {
"description": "Whether patients are allowed to edit intake forms",
"type": "boolean",
"example": true
},
"notification_enabled": {
"description": "Whether notifications are enabled for patients",
"type": "boolean",
"example": true
},
"sms_notification_enabled": {
"description": "Whether SMS notifications are enabled for patients",
"type": "boolean",
"example": true
},
"email_notification_enabled": {
"description": "Whether email notifications are enabled for patients",
"type": "boolean",
"example": true
},
"attribute_preferences": {
"description": "Client attribute permissions for patient experience",
"type": "array",
"items": {
"$ref": "#/components/schemas/PeSettingAttributePermissionResource"
}
}
},
"type": "object"
},
"PendingInvitationResource": {
"title": "Pending Invitation Resource",
"description": "Pending team member invitation data",
"properties": {
"id": {
"description": "Invitation ID (prefixed with 'inv_' to distinguish from user IDs)",
"type": "string",
"example": "inv_1"
},
"invitation_id": {
"description": "Actual invitation ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Invitee full name",
"type": "string",
"example": "John Doe"
},
"email": {
"description": "Invitee email address",
"type": "string",
"format": "email",
"example": "john.doe@example.com"
},
"phone_number": {
"description": "Invitee phone number",
"type": "string",
"example": "+1234567890",
"nullable": true
},
"invitation_status": {
"description": "Invitation status",
"type": "string",
"enum": [
"pending",
"expired"
],
"example": "pending"
},
"invited_at": {
"description": "When the invitation was sent",
"type": "string",
"format": "date-time",
"example": "2024-06-15T14:30:00Z"
},
"expires_at": {
"description": "When the invitation expires",
"type": "string",
"format": "date-time",
"example": "2024-06-22T14:30:00Z",
"nullable": true
},
"invited_by": {
"description": "Name of user who sent the invitation",
"type": "string",
"example": "Jane Admin",
"nullable": true
},
"has_accepted": {
"description": "Always false for pending invitations",
"type": "boolean",
"example": false
},
"is_pending_invitation": {
"description": "Flag to identify this as a pending invitation",
"type": "boolean",
"example": true
},
"roles": {
"description": "Roles the invitee will have when they accept",
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"example": "TEAM_MEMBER"
},
"locations": {
"type": "array",
"items": {
"type": "object"
}
},
"stations": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"ProviderBaseResource": {
"required": [
"id",
"name",
"is_active",
"email",
"location_count",
"service_count",
"appointment_types",
"created_at"
],
"properties": {
"id": {
"description": "Provider ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Provider name",
"type": "string",
"example": "Dr. John Smith"
},
"image": {
"description": "Provider image URL",
"type": "string",
"example": "https://example.com/images/provider.jpg",
"nullable": true
},
"description": {
"description": "Provider description",
"type": "string",
"example": "Primary care physician with 10 years of experience",
"nullable": true
},
"phone_number": {
"description": "Provider phone number",
"type": "string",
"example": "+1-555-0123",
"nullable": true
},
"is_active": {
"description": "Whether the provider is active",
"type": "boolean",
"example": true
},
"email": {
"description": "Provider email address",
"type": "string",
"example": "john.smith@example.com",
"nullable": true
},
"location_count": {
"description": "Number of locations associated with this provider",
"type": "integer",
"example": 3
},
"service_count": {
"description": "Number of services associated with this provider",
"type": "integer",
"example": 5
},
"appointment_types": {
"description": "Appointment type availability",
"properties": {
"schedule_on": {
"description": "Whether scheduled appointments are enabled",
"type": "boolean",
"example": true
},
"walk_in_on": {
"description": "Whether walk-in appointments are enabled",
"type": "boolean",
"example": false
}
},
"type": "object"
},
"rating": {
"description": "Average rating (if available)",
"type": "number",
"format": "float",
"example": 4.5,
"nullable": true
},
"created_at": {
"description": "Creation timestamp",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
},
"ProviderClientChatMetaDataResource": {
"required": [
"id",
"client_name",
"is_online",
"last_message",
"last_message_at",
"unread_message_count",
"delivery_status"
],
"properties": {
"id": {
"description": "Client ID",
"type": "integer",
"example": 123
},
"client_name": {
"description": "Client full name",
"type": "string",
"example": "Jane Doe"
},
"profile_picture": {
"description": "Client profile picture URL",
"type": "string",
"example": "https://example.com/profile.jpg",
"nullable": true
},
"is_online": {
"description": "Whether the client is currently online",
"type": "boolean",
"example": true
},
"last_message": {
"description": "Last message text in the conversation",
"type": "string",
"example": "Thank you for your help!",
"nullable": true
},
"last_message_at": {
"description": "Timestamp of the last message",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
},
"unread_message_count": {
"description": "Number of unread messages from this client",
"type": "integer",
"example": 3
},
"delivery_status": {
"description": "Delivery status of the last message",
"type": "string",
"enum": [
"seen",
"delivered"
],
"example": "seen"
}
},
"type": "object"
},
"ProviderDetailResource": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ProviderBaseResource"
},
{
"properties": {
"rating": {
"description": "Average provider rating",
"type": "number",
"format": "float",
"example": 4.5
},
"locations": {
"description": "List of locations associated with this provider",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Clinic"
}
},
"type": "object"
}
}
},
"type": "object"
}
]
},
"ProviderFormResource": {
"required": [
"id",
"name",
"type",
"status",
"submittion_count",
"location_count"
],
"properties": {
"id": {
"description": "Form UUID",
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"name": {
"description": "Form name",
"type": "string",
"example": "Patient Intake Form"
},
"type": {
"description": "Form type",
"type": "string",
"enum": [
"intake",
"service",
"feedback",
"referral",
"inquiry"
],
"example": "intake"
},
"status": {
"description": "Form status",
"type": "string",
"enum": [
"draft",
"live",
"unpublished"
],
"example": "live"
},
"submittion_count": {
"description": "Number of form submissions for this provider",
"type": "integer",
"example": 42
},
"location_count": {
"description": "Number of locations where this form is available for this provider",
"type": "integer",
"example": 3
}
},
"type": "object"
},
"ProviderIncomingReferralResource": {
"required": [
"id",
"status",
"date_submitted",
"partner"
],
"properties": {
"id": {
"description": "Referral UUID",
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"client_name": {
"description": "Client name",
"type": "string",
"example": "Jane Doe",
"nullable": true
},
"email": {
"description": "Client email",
"type": "string",
"example": "jane.doe@example.com",
"nullable": true
},
"status": {
"description": "Referral status",
"type": "string",
"enum": [
"pending",
"accepted",
"rejected",
"completed",
"auto_declined"
],
"example": "pending"
},
"date_submitted": {
"description": "Date when referral was received",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z",
"nullable": true
},
"partner": {
"description": "Name of the partner business that sent the referral",
"type": "string",
"example": "Partner Clinic"
}
},
"type": "object"
},
"ProviderOutgoingReferralResource": {
"required": [
"id",
"client_name",
"date_submitted",
"partner",
"status"
],
"properties": {
"id": {
"description": "Form response UUID",
"type": "string",
"format": "uuid",
"example": "9d2b5335-0d2d-4016-8f97-26fe9cc8215f"
},
"client_name": {
"description": "Client name",
"type": "string",
"example": "John Doe",
"nullable": true
},
"email": {
"description": "Client email",
"type": "string",
"example": "john.doe@example.com",
"nullable": true
},
"date_submitted": {
"description": "Date when form was submitted",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z",
"nullable": true
},
"partner": {
"description": "Partner business name or count of partners (if multiple)",
"type": "string",
"example": "Partner Clinic"
},
"status": {
"description": "Overall referral status",
"type": "string",
"enum": [
"pending",
"pending request",
"accepted",
"rejected",
"completed",
"declined"
],
"example": "pending request"
}
},
"type": "object"
},
"ProviderServiceResource": {
"required": [
"id",
"name",
"type",
"location_count",
"form_count",
"created_at"
],
"properties": {
"id": {
"description": "Service ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Service name",
"type": "string",
"example": "General Consultation"
},
"type": {
"description": "Service type",
"type": "string",
"example": "internal"
},
"location_count": {
"description": "Number of locations where this service is available for this provider",
"type": "integer",
"example": 3
},
"form_count": {
"description": "Number of forms associated with this service for this provider",
"type": "integer",
"example": 2
},
"time_in_minute": {
"description": "Service duration in minutes",
"type": "integer",
"example": 30,
"nullable": true
},
"is_available": {
"description": "Whether the service is available",
"type": "boolean",
"example": true,
"nullable": true
},
"auto_approve": {
"description": "Whether appointments are auto-approved",
"type": "boolean",
"example": false,
"nullable": true
},
"is_visible": {
"description": "Whether the service is visible to clients",
"type": "boolean",
"example": true,
"nullable": true
},
"created_at": {
"description": "Creation timestamp",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00.000Z"
}
},
"type": "object"
},
"BookingDetailResource": {
"title": "Booking Detail Resource",
"description": "Comprehensive booking details including client, workspace, schedule, payment, and history",
"properties": {
"id": {
"description": "Booking ID",
"type": "string",
"example": "776ffb8f-3893-41c1-b579-2a22965c8294"
},
"booking_type": {
"description": "$resource;",
"type": "string",
"enum": [
"walk_in",
"schedule"
],
"example": "schedule"
},
"client_id": {
"description": "$resource;",
"type": "integer",
"example": 123
},
"service_id": {
"description": "$resource;",
"type": "integer",
"example": 5
},
"location_station_id": {
"description": "$resource;",
"type": "integer",
"example": 10
},
"appointment_method_id": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"location_id": {
"description": "$resource;",
"type": "integer",
"example": 2
},
"status": {
"description": "$resource;",
"type": "string",
"example": "confirmed"
},
"made_by": {
"description": "$resource;",
"type": "string",
"example": "admin"
},
"status_updated_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:00:00Z"
},
"booking_date": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"example": "2024-01-30T14:00:00Z"
},
"appointment_date": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"example": "2024-01-30T14:00:00Z"
},
"booking_reference": {
"description": "$resource;",
"type": "string",
"example": "ORG-20251107-C0ELH"
},
"location_order": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"check_in_status": {
"description": "$resource;",
"type": "string",
"example": "checked_in"
},
"priority": {
"description": "$resource;",
"type": "string",
"example": "normal"
},
"is_follow_up": {
"description": "$resource;",
"type": "boolean",
"example": false
},
"through": {
"description": "$resource;",
"type": "string",
"example": "web"
},
"source": {
"description": "$resource;",
"type": "string",
"example": "Web"
},
"check_requested_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"check_in_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"service_start_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"service_end_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelled_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelled_by": {
"description": "$resource;",
"type": "integer",
"nullable": true
},
"cancellation_reason": {
"description": "$resource;",
"type": "string",
"nullable": true
},
"confirmed_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"confirmed_by": {
"description": "$resource;",
"type": "integer",
"nullable": true
},
"business_id": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"time_zone": {
"description": "$resource;",
"type": "string",
"example": "America/New_York"
},
"duration": {
"description": "$resource;",
"type": "integer",
"example": 30
},
"booking_will_end_at": {
"description": "$resource;",
"type": "string",
"format": "date-time",
"nullable": true
},
"status_info": {
"description": "$resource;",
"properties": {
"current_status": {
"description": "$resource;",
"type": "string",
"example": "confirmed"
},
"label": {
"description": "$resource;",
"type": "string",
"example": "Confirmed"
},
"color": {
"description": "$resource;",
"type": "string",
"example": "#4CAF50"
},
"description": {
"description": "$resource;",
"type": "string",
"example": "Your appointment is confirmed"
},
"next_possible_actions": {
"description": "$resource;",
"type": "array",
"items": {
"type": "string",
"example": "cancel"
}
}
},
"type": "object"
},
"client": {
"description": "Client details with categories",
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 123
},
"full_name": {
"description": "$resource;",
"type": "string",
"example": "John Doe"
},
"email": {
"description": "$resource;",
"type": "string",
"example": "john@example.com"
},
"phone_number": {
"description": "$resource;",
"type": "string",
"example": "1234567890"
},
"avatar_url": {
"description": "$resource;",
"type": "string",
"example": "https://example.com/avatar.jpg"
},
"categories": {
"description": "$resource;",
"type": "array",
"items": {
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"name": {
"description": "$resource;",
"type": "string",
"example": "VIP"
},
"color": {
"description": "$resource;",
"type": "string",
"example": "#FFD700"
}
},
"type": "object"
}
}
},
"type": "object"
},
"actions": {
"description": "$resource;",
"properties": {
"can_cancel": {
"description": "$resource;",
"type": "boolean",
"example": true
},
"can_reschedule": {
"description": "$resource;",
"type": "boolean",
"example": true
},
"can_modify": {
"description": "$resource;",
"type": "boolean",
"example": true
},
"can_check_in": {
"description": "$resource;",
"type": "boolean",
"example": true
},
"cancel_deadline": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"reschedule_deadline": {
"description": "$resource;",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"details": {
"description": "$resource;",
"properties": {
"notes": {
"description": "$resource;",
"type": "string",
"example": "Patient notes"
},
"internal_notes": {
"description": "$resource;",
"type": "string",
"example": "Internal notes"
},
"special_requirements": {
"description": "$resource;",
"type": "string",
"example": "Wheelchair accessible"
},
"booked_by": {
"description": "$resource;",
"type": "string",
"example": "admin"
},
"created_at": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"created_at_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"updated_at_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"payment": {
"description": "$resource;",
"properties": {
"total_amount": {
"description": "$resource;",
"type": "number",
"example": 85
},
"currency": {
"description": "$resource;",
"type": "string",
"example": "USD"
},
"status": {
"description": "$resource;",
"type": "string",
"example": "pending"
},
"payment_methods": {
"description": "$resource;",
"type": "array",
"items": {
"type": "string"
},
"example": [
"card",
"cash",
"insurance"
]
},
"insurance_accepted": {
"description": "$resource;",
"type": "boolean",
"example": true
}
},
"type": "object"
},
"history": {
"description": "$resource;",
"type": "array",
"items": {
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"appointment": {
"description": "$resource;",
"type": "integer",
"example": 123
},
"action": {
"description": "$resource;",
"type": "string",
"example": "checked_in"
},
"details": {
"description": "$resource;",
"type": "object"
},
"performed_by": {
"description": "$resource;",
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"username": {
"description": "$resource;",
"type": "string",
"example": "admin"
},
"email": {
"description": "$resource;",
"type": "string",
"example": "admin@example.com"
},
"full_name": {
"description": "$resource;",
"type": "string",
"example": "Admin User"
}
},
"type": "object",
"nullable": true
},
"timestamp": {
"description": "$resource;",
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"reminders": {
"description": "$resource;",
"type": "array",
"items": {
"type": "object"
}
},
"schedule": {
"description": "$resource;",
"properties": {
"start_time": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"end_time": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"timezone": {
"description": "$resource;",
"type": "string",
"example": "America/New_York"
},
"start_time_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"end_time_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"duration_minutes": {
"description": "$resource;",
"type": "integer",
"example": 30
},
"date": {
"description": "$resource;",
"type": "string",
"format": "date",
"example": "2024-01-30"
},
"time": {
"description": "$resource;",
"type": "string",
"example": "14:00:00"
}
},
"type": "object"
},
"qr_code": {
"description": "$resource;",
"properties": {
"check_in_url": {
"description": "$resource;",
"type": "string",
"example": "https://app.example.com/check-in/ORG-20251107-C0ELH"
},
"qr_code_image": {
"description": "$resource;",
"type": "string",
"example": "/api/appointments/776ffb8f-3893-41c1-b579-2a22965c8294/qr-code"
}
},
"type": "object"
},
"organization": {
"description": "$resource;",
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"name": {
"description": "$resource;",
"type": "string",
"example": "Healthcare Plus"
}
},
"type": "object"
},
"location": {
"description": "$resource;",
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 2
},
"name": {
"description": "$resource;",
"type": "string",
"example": "Main Branch"
},
"address": {
"description": "$resource;",
"type": "string",
"example": "123 Main St"
},
"phone": {
"description": "$resource;",
"type": "string",
"example": "555-0100"
},
"coordinates": {
"description": "$resource;",
"properties": {
"lat": {
"description": "$resource;",
"type": "number",
"example": 40.7128
},
"lng": {
"description": "$resource;",
"type": "number",
"example": -74.006
}
},
"type": "object"
},
"amenities": {
"description": "$resource;",
"properties": {
"parking": {
"description": "$resource;",
"type": "boolean",
"example": true
},
"wheelchair_accessible": {
"description": "$resource;",
"type": "boolean",
"example": true
},
"wifi": {
"description": "$resource;",
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
},
"station": {
"description": "$resource;",
"properties": {
"id": {
"description": "$resource;",
"type": "integer",
"example": 10
},
"name": {
"description": "$resource;",
"type": "string",
"example": "Consultation Room 1"
},
"type": {
"description": "$resource;",
"type": "string",
"example": "Consultation Room"
},
"floor": {
"description": "$resource;",
"type": "integer",
"example": 1
},
"amenities": {
"description": "$resource;",
"type": "array",
"items": {
"type": "string"
},
"example": [
"wheelchair_accessible",
"air_conditioned"
]
}
},
"type": "object"
},
"service": {
"$ref": "#/components/schemas/SimpleServiceResource"
},
"start_time": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"end_time": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"created_at": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"start_time_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"end_time_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"created_at_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"updated_at_utc": {
"description": "$resource;",
"type": "string",
"format": "date-time"
},
"organization_timezone": {
"description": "$resource;",
"type": "string",
"example": "America/New_York"
}
},
"type": "object"
},
"BookingProviderResource": {
"description": "Basic provider/station information",
"properties": {
"id": {
"description": "Provider ID",
"type": "integer",
"example": 1
},
"location_station_id": {
"description": "Location station ID",
"type": "integer",
"example": 1
},
"station_id": {
"description": "Station ID",
"type": "integer",
"example": 5
},
"station_name": {
"description": "Station name",
"type": "string",
"example": "Station A"
},
"location_id": {
"description": "Location ID",
"type": "integer",
"example": 10
}
},
"type": "object"
},
"BookingResource": {
"title": "Booking Resource",
"description": "Booking resource with client, station, location, and service details",
"properties": {
"id": {
"description": "Booking ID",
"type": "string",
"example": "bk_abc123"
},
"booking_type": {
"description": "Type of booking",
"type": "string",
"enum": [
"walk_in",
"schedule"
],
"example": "walk_in"
},
"booking_reference": {
"description": "Booking reference code",
"type": "string",
"example": "REF123456"
},
"status": {
"description": "Current booking status",
"type": "string",
"example": "checked-in"
},
"check_in_status": {
"description": "Check-in status",
"type": "string",
"example": "checked_in"
},
"priority": {
"description": "Booking priority level",
"type": "string",
"example": "normal"
},
"is_follow_up": {
"description": "Whether this is a follow-up booking",
"type": "boolean",
"example": false
},
"client_id": {
"description": "Client ID",
"type": "integer",
"example": 123
},
"service_id": {
"description": "Service ID",
"type": "integer",
"example": 45
},
"made_by": {
"description": "Who created the booking",
"type": "string",
"example": "admin"
},
"joined_via": {
"description": "How the booking was created",
"type": "string",
"example": "Admin"
},
"appointment_method": {
"description": "Appointment method",
"type": "string",
"example": "In Person"
},
"duration": {
"description": "Duration in minutes",
"type": "integer",
"example": 30
},
"booking_time": {
"description": "Formatted booking time",
"type": "string",
"example": "2 hours ago"
},
"joined_at": {
"description": "When the booking was created",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:00:00Z"
},
"appointment_date": {
"description": "Scheduled appointment date",
"type": "string",
"format": "date-time",
"example": "2024-01-30T14:00:00Z"
},
"status_updated_at": {
"description": "When the status was last updated",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:30:00Z"
},
"service_start_at": {
"description": "When the service started",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:00:00Z"
},
"service_end_at": {
"description": "When the service ended",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:30:00Z"
},
"client": {
"$ref": "#/components/schemas/SimpleClientResource"
},
"station": {
"$ref": "#/components/schemas/BookingProviderResource"
},
"location": {
"description": "Location information",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Branch"
}
},
"type": "object"
},
"service": {
"description": "Service information",
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Consultation"
}
},
"type": "object"
}
},
"type": "object"
},
"LocationWithProvidersResource": {
"title": "Location With Providers Resource",
"description": "Location details including its available providers/stations",
"properties": {
"id": {
"description": "Location ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Location name",
"type": "string",
"example": "Main Clinic"
},
"providers": {
"description": "List of providers/stations available at this location",
"type": "array",
"items": {
"$ref": "#/components/schemas/BookingProviderResource"
}
}
},
"type": "object"
},
"QueueBookingResource": {
"title": "Queue Booking Resource",
"description": "Queue booking with position, client, station, location, and service details",
"properties": {
"position": {
"description": "Position in queue",
"type": "integer",
"example": 1
},
"id": {
"description": "Booking ID",
"type": "string",
"example": "bk_abc123"
},
"booking_type": {
"description": "Type of booking",
"type": "string",
"enum": [
"walk_in",
"schedule"
],
"example": "walk_in"
},
"booking_reference": {
"description": "Booking reference code",
"type": "string",
"example": "REF123456"
},
"status": {
"description": "Current booking status",
"type": "string",
"example": "checked-in"
},
"check_in_status": {
"description": "Check-in status",
"type": "string",
"example": "checked_in"
},
"priority": {
"description": "Booking priority level",
"type": "string",
"example": "normal"
},
"is_follow_up": {
"description": "Whether this is a follow-up booking",
"type": "boolean",
"example": false
},
"client_id": {
"description": "Client ID",
"type": "integer",
"example": 123
},
"service_id": {
"description": "Service ID",
"type": "integer",
"example": 45
},
"made_by": {
"description": "Who created the booking",
"type": "string",
"example": "admin"
},
"joined_via": {
"description": "How the booking was created",
"type": "string",
"example": "Admin"
},
"appointment_method": {
"description": "Appointment method",
"type": "string",
"example": "In Person"
},
"duration": {
"description": "Duration in minutes",
"type": "integer",
"example": 30
},
"booking_time": {
"description": "Formatted booking time",
"type": "string",
"example": "2 hours ago"
},
"joined_at": {
"description": "When the booking was created",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:00:00Z"
},
"appointment_date": {
"description": "Scheduled appointment date",
"type": "string",
"format": "date-time",
"example": "2024-01-30T14:00:00Z"
},
"status_updated_at": {
"description": "When the status was last updated",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:30:00Z"
},
"service_start_at": {
"description": "When the service started",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:00:00Z"
},
"service_end_at": {
"description": "When the service ended",
"type": "string",
"format": "date-time",
"example": "2024-01-30T10:30:00Z"
},
"client": {
"$ref": "#/components/schemas/SimpleClientResource"
},
"station": {
"$ref": "#/components/schemas/BookingProviderResource"
},
"location": {
"description": "Location information",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Main Branch"
}
},
"type": "object"
},
"service": {
"description": "Service information",
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Consultation"
}
},
"type": "object"
}
},
"type": "object"
},
"SimpleClientResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"external_id": {
"type": "string",
"example": "123456"
},
"full_name": {
"type": "string",
"example": "Alice Smith"
},
"email": {
"type": "string",
"example": "alice@example.com"
},
"priority": {
"description": "Client priority level",
"type": "string",
"example": "regular"
},
"phone_number": {
"type": "string",
"example": "1234567890"
},
"profile_picture_url": {
"type": "string",
"example": "https://example.com/pic.jpg"
},
"is_active": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"SimpleServiceResource": {
"description": "Simple service information with appointment methods",
"properties": {
"id": {
"description": "Service ID",
"type": "integer",
"example": 5
},
"name": {
"description": "Service name",
"type": "string",
"example": "General Consultation"
},
"methods": {
"description": "Available appointment methods",
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "In Person"
},
"duration": {
"type": "integer",
"example": 30
}
},
"type": "object"
}
}
},
"type": "object"
},
"UserQueuePreferenceResource": {
"title": "User Queue Preference Resource",
"description": "User's personalized queue filtering and display preferences",
"properties": {
"selected_location_id": {
"description": "Currently selected location ID",
"type": "integer",
"example": 1
},
"provider_selections": {
"properties": {
"all_selected": {
"type": "boolean",
"example": true
},
"selected": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BookingProviderResource"
}
}
},
"type": "object"
},
"service_selections": {
"properties": {
"all_selected": {
"type": "boolean",
"example": false
},
"selected": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SimpleServiceResource"
}
}
},
"type": "object"
},
"joined_from": {
"properties": {
"all_selected": {
"type": "boolean",
"example": true
},
"selected": {
"type": "array",
"items": {
"type": "string",
"example": "Admin"
}
}
},
"type": "object"
},
"show_walk_in": {
"type": "boolean",
"example": true
},
"show_scheduled": {
"type": "boolean",
"example": true
},
"show_pending_appointments": {
"type": "boolean",
"example": false
},
"show_provider": {
"type": "boolean",
"example": true
},
"show_service": {
"type": "boolean",
"example": true
},
"show_joined_from": {
"type": "boolean",
"example": false
},
"show_appointment_method": {
"type": "boolean",
"example": true
},
"show_appointment_type": {
"type": "boolean",
"example": true
},
"auto_flow": {
"type": "boolean",
"example": true
},
"is_queue_active": {
"type": "boolean",
"example": true
},
"allow_toast_notifications": {
"type": "boolean",
"example": true
},
"popup_duration": {
"type": "integer",
"example": 5
},
"allow_walk_in_appointments": {
"type": "boolean",
"example": true
},
"auto_approve_walk_in_appointments": {
"type": "boolean",
"example": false
},
"max_patients_allowed_to_join": {
"type": "integer",
"example": 50
},
"page_layout": {
"type": "string",
"enum": [
"column",
"grid"
],
"example": "column"
}
},
"type": "object"
},
"BaseReferralServiceResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "General Consultation"
},
"partner_count": {
"description": "partner count",
"type": "integer",
"example": "2"
},
"is_active": {
"type": "boolean",
"example": true
},
"type": {
"type": "string",
"example": "incoming"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"ReferralPartnerInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ReferralServiceResource"
},
{
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Partner Clinic"
},
"type": {
"type": "string",
"example": "partner_type"
}
},
"type": "object"
}
]
},
"ReferralServiceDetailResource": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseReferralServiceResource"
},
{
"$ref": "#/components/schemas/ReferralServiceResource"
},
{
"properties": {
"partners": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReferralPartnerInfo"
}
}
},
"type": "object"
}
]
},
"ReferralServiceResource": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "General Consultation"
},
"partner_count": {
"description": "partner count",
"type": "integer",
"example": "2"
},
"is_available": {
"type": "boolean",
"example": true
},
"type": {
"type": "string",
"example": "incoming"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"UserTeamMemberResource": {
"title": "User Team Member Resource",
"description": "Team member user data with role information",
"properties": {
"id": {
"description": "User ID",
"type": "integer",
"example": 1
},
"name": {
"description": "User full name",
"type": "string",
"example": "John Doe"
},
"email": {
"description": "User email address",
"type": "string",
"format": "email",
"example": "john.doe@example.com"
},
"phone_number": {
"description": "User phone number",
"type": "string",
"example": "+1234567890",
"nullable": true
},
"on_boarded_date": {
"description": "When the user joined this organization as a team member",
"type": "string",
"format": "date-time",
"example": "2024-06-15T14:30:00Z"
},
"has_accepted": {
"description": "Whether the user has accepted the invitation",
"type": "boolean",
"example": true
},
"roles": {
"description": "Array of user roles and their associated locations/stations",
"type": "array",
"items": {
"properties": {
"role": {
"description": "Role type",
"type": "string",
"enum": [
"BUSINESS_MANAGER",
"LOCATION_MANAGER",
"STATION_MANAGER",
"SERVICE_PROVIDER",
"TEAM_MEMBER"
],
"example": "TEAM_MEMBER"
},
"locations": {
"description": "Associated locations for this role",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Location ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Location name",
"type": "string",
"example": "Main Branch"
}
},
"type": "object"
}
},
"stations": {
"description": "Associated stations for this role",
"type": "array",
"items": {
"properties": {
"id": {
"description": "Station ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Station name",
"type": "string",
"example": "Reception"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"WalkInCancellationSettingResource": {
"title": "Walk-In Cancellation Settings",
"description": "Cancellation rules configuration for walk-ins",
"properties": {
"allow_cancellation_with_alert": {
"type": "boolean",
"example": true
},
"cancellation_alert": {
"properties": {
"time_threshold": {
"type": "integer",
"example": 30
},
"time_unit": {
"type": "string",
"enum": [
"minutes",
"hours",
"days"
],
"example": "minutes"
},
"relation": {
"type": "string",
"enum": [
"before",
"after"
],
"example": "before"
}
},
"type": "object",
"nullable": true
},
"custom_messages": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "reminder-1"
},
"content": {
"type": "string",
"example": "Your walk-in booking will start soon."
},
"character_count": {
"type": "integer",
"example": 35
},
"max_characters": {
"type": "integer",
"example": 160
},
"delivery_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"in_app",
"sms",
"email"
]
}
},
"conditions": {
"type": "array",
"items": {
"type": "string",
"example": "before_start"
},
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
},
"WalkInGeneralSettingResource": {
"title": "Walk-In General Settings",
"description": "General walk-in configuration",
"properties": {
"wait_time_calculation": {
"properties": {
"method": {
"type": "string",
"enum": [
"historical_average",
"custom"
],
"example": "custom"
},
"custom_wait_time": {
"description": "Custom wait time in minutes",
"type": "integer",
"example": 15,
"nullable": true
}
},
"type": "object"
},
"queue_length_cap": {
"properties": {
"method": {
"type": "string",
"enum": [
"historical_average",
"custom"
],
"example": "custom"
},
"custom_wait_time": {
"description": "Custom wait time in minutes",
"type": "integer",
"example": 15,
"nullable": true
}
},
"type": "object"
},
"allow_walk_ins": {
"type": "boolean",
"example": true
},
"carry_over_walk_ins": {
"type": "boolean",
"example": true
},
"maximum_allowed_late_time": {
"description": "Maximum lateness allowed in minutes",
"type": "integer",
"example": 10
}
},
"type": "object"
},
"WalkInPatientExperienceSettingResource": {
"title": "Walk-In Patient Experience Settings",
"description": "Patient experience walk-in configuration for business/location/station",
"properties": {
"show_queue_position": {
"type": "boolean",
"example": true
},
"show_estimated_wait_time": {
"type": "boolean",
"example": true
},
"show_real_time_updates": {
"type": "boolean",
"example": false
},
"update_frequency": {
"description": "Update frequency in minutes",
"type": "integer",
"example": 5,
"nullable": true
}
},
"type": "object"
},
"WalkInSettingResource": {
"title": "Walk-In Settings",
"description": "Full walk-in configuration for business/location/station",
"properties": {
"general": {
"$ref": "#/components/schemas/WalkInGeneralSettingResource"
},
"patient_experience": {
"$ref": "#/components/schemas/WalkInPatientExperienceSettingResource"
},
"cancellation_rules": {
"$ref": "#/components/schemas/WalkInCancellationSettingResource"
}
},
"type": "object"
},
"SimpleWorkspaceInfoResource": {
"properties": {
"id": {
"type": "integer",
"example": 201
},
"name": {
"type": "string",
"example": "Central Station"
}
},
"type": "object"
},
"HeaderError": {
"description": "Header validation error types",
"type": "string",
"enum": [
"missing_label",
"invalid_label"
],
"example": "missing_label"
},
"ImportSessionDTO": {
"description": "Data Transfer Object for import session management",
"properties": {
"sessionId": {
"description": "Session identifier",
"type": "string",
"example": "session_123"
},
"fileName": {
"description": "Name of uploaded file",
"type": "string",
"example": "import_data.csv"
},
"uploadedAt": {
"description": "Upload timestamp",
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"sheets": {
"description": "Array of sheet data",
"type": "array",
"items": {
"$ref": "#/components/schemas/SheetDTO"
}
}
},
"type": "object"
},
"RowDTO": {
"description": "Data Transfer Object for import row data",
"properties": {
"tempSessionId": {
"description": "Temporary session identifier",
"type": "string",
"example": "temp_123"
},
"sheetId": {
"description": "Sheet identifier",
"type": "string",
"example": "sheet_001"
},
"rowIndex": {
"description": "Row index in the sheet",
"type": "integer",
"example": 1
},
"rawData": {
"description": "Raw row data from file",
"type": "array",
"items": {
"type": "string"
}
},
"parsedData": {
"description": "Parsed row data",
"type": "array",
"items": {
"type": "string"
}
},
"validationStatus": {
"$ref": "#/components/schemas/ValidationStatus"
},
"errors": {
"description": "Validation errors",
"type": "array",
"items": {
"type": "string"
}
},
"isEdited": {
"description": "Whether row has been edited",
"type": "boolean",
"example": false
}
},
"type": "object"
},
"SheetDTO": {
"description": "Data Transfer Object for sheet data",
"properties": {
"id": {
"description": "Sheet identifier",
"type": "string",
"example": "sheet_001"
},
"sheetName": {
"description": "Sheet name",
"type": "string",
"example": "Customers"
},
"headers": {
"description": "Sheet headers",
"type": "array",
"items": {
"$ref": "#/components/schemas/SheetHeaderDto"
},
"nullable": true
},
"rows": {
"description": "Sheet rows",
"type": "array",
"items": {
"$ref": "#/components/schemas/RowDTO"
}
},
"isSelected": {
"description": "Whether sheet is selected for import",
"type": "boolean",
"example": true
}
},
"type": "object"
},
"SheetHeaderDto": {
"description": "Data Transfer Object for sheet header information",
"properties": {
"id": {
"description": "Header identifier",
"type": "string",
"example": "header_001"
},
"labelOnFile": {
"description": "Label as it appears in the file",
"type": "string",
"example": "Customer Name",
"nullable": true
},
"systemFieldKey": {
"description": "System field key for mapping",
"type": "string",
"example": "client_name",
"nullable": true
},
"sheetId": {
"description": "Sheet identifier",
"type": "string",
"example": "sheet_001"
}
},
"type": "object"
},
"ValidationStatus": {
"description": "Validation status for import data",
"type": "string",
"enum": [
"valid",
"invalid",
"pending"
],
"example": "valid"
},
"UnauthorizedResponse": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
},
"type": "object"
},
"SuccessResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Operation completed successfully"
},
"data": {
"type": "object",
"nullable": true
},
"meta": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"CreatedResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Resource created successfully"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"RetrievedResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Resource retrieved successfully"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"UpdatedResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Resource updated successfully"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"DeletedResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Resource deleted successfully"
},
"data": {
"type": "null",
"example": null
}
},
"type": "object"
},
"NotFoundResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "The requested resource was not found"
},
"error": {
"type": "string",
"example": "NotFound"
},
"errors": {
"type": "object",
"example": [],
"nullable": true
}
},
"type": "object"
},
"ForbiddenResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Access forbidden"
},
"error": {
"type": "string",
"example": "Forbidden"
}
},
"type": "object"
},
"BadRequestResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request"
},
"error": {
"type": "string",
"example": "BadRequest"
},
"errors": {
"type": "object",
"example": {
"field": "Invalid field value"
},
"nullable": true
}
},
"type": "object"
},
"MethodNotAllowedResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Method not allowed"
},
"error": {
"type": "string",
"example": "MethodNotAllowed"
}
},
"type": "object"
},
"ConflictResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Resource conflict"
},
"error": {
"type": "string",
"example": "Conflict"
},
"errors": {
"type": "object",
"example": {
"resource": "Resource already exists"
},
"nullable": true
}
},
"type": "object"
},
"ServerErrorResponse": {
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Internal server error"
},
"error": {
"type": "string",
"example": "InternalServerError"
},
"errors": {
"type": "object",
"example": {
"system": "An unexpected error occurred"
},
"nullable": true
}
},
"type": "object"
}
},
"responses": {
"400": {
"description": "Bad Request - Invalid client or business mismatch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"401": {
"description": "Unauthorized - Client does not belong to business",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"Unauthorized": {
"description": "Unauthorized - Invalid or missing authentication token",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
},
"error_code": {
"type": "string",
"example": "UNAUTHORIZED"
}
},
"type": "object"
}
}
}
},
"Forbidden": {
"description": "Forbidden - Insufficient permissions",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"error_code": {
"type": "string",
"example": "FORBIDDEN"
}
},
"type": "object"
}
}
}
},
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Resource not found"
},
"error_code": {
"type": "string",
"example": "NOT_FOUND"
}
},
"type": "object"
}
}
}
},
"RateLimited": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateLimitResponse"
}
}
}
},
"ValidationError": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
}
},
"ServerError": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"UnauthorizedError": {
"description": "Unauthorized - Authentication required",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthenticated"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"User is not authenticated."
]
}
},
"type": "object"
}
}
}
},
"ForbiddenError": {
"description": "Forbidden - Insufficient permissions",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Forbidden"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"You are not authorized for this business."
]
}
},
"type": "object"
}
}
}
},
"OrganizationNotFound": {
"description": "Organization not found",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Business not found"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"No business found for the given organization ID."
]
}
},
"type": "object"
}
}
}
},
"FormNotFound": {
"description": "Form not found or does not belong to organization",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Resource not found."
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"The requested form does not exist or does not belong to this organization."
]
}
},
"type": "object"
}
}
}
},
"MissingOrganizationHeader": {
"description": "Missing X-organizationId header",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing organization header"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"X-organizationId header is required."
]
}
},
"type": "object"
}
}
}
}
},
"parameters": {
"page": {
"name": "page",
"in": "query",
"description": "Page number for pagination",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1,
"example": 1
}
},
"per_page": {
"name": "per_page",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100,
"minimum": 1,
"example": 15
}
},
"sort": {
"name": "sort",
"in": "query",
"description": "Sort field",
"required": false,
"schema": {
"type": "string",
"example": "created_at"
}
},
"order": {
"name": "order",
"in": "query",
"description": "Sort order",
"required": false,
"schema": {
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc"
],
"example": "desc"
}
},
"search": {
"name": "search",
"in": "query",
"description": "Search term",
"required": false,
"schema": {
"type": "string",
"example": "john@example.com"
}
},
"OrganizationIdHeader": {
"name": "X-organizationId",
"in": "header",
"description": "Organization ID for business context. This header is required for all organization-scoped endpoints.",
"required": true,
"schema": {
"type": "integer",
"minimum": 1,
"example": 1
}
},
"LocationIdHeader": {
"name": "X-locationId",
"in": "header",
"description": "Optional location ID for location-specific operations within the organization.",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 5
}
},
"StationIdHeader": {
"name": "X-stationId",
"in": "header",
"description": "Optional station ID for station-specific operations within the organization.",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 10
}
},
"OrganizationHeader": {
"name": "X-organizationId",
"in": "header",
"description": "Organization ID to retrieve form responses for",
"required": true,
"schema": {
"type": "integer",
"example": 1
}
},
"LocationIdsFilter": {
"name": "location_ids[]",
"in": "query",
"description": "Filter by locations (e.g., North York Medical)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"FormTypesFilter": {
"name": "form_types[]",
"in": "query",
"description": "Filter by form types",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"intake",
"service",
"feedback",
"referral",
"inquiry"
],
"example": "service"
}
}
},
"FormStatusesFilter": {
"name": "form_statuses[]",
"in": "query",
"description": "Filter by form statuses (e.g., Live, Draft, Unpublished)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"draft",
"live",
"unpublished"
],
"example": "live"
}
}
},
"ResponseStatusesFilter": {
"name": "response_statuses[]",
"in": "query",
"description": "Filter by form response statuses (e.g., Pending, Completed)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"pending",
"completed",
"blocked",
"approved",
"declined"
],
"example": "pending"
}
}
},
"FlagsFilter": {
"name": "flags[]",
"in": "query",
"description": "Filter by flags (e.g., Urgent Attention)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"urgent_attention",
"follow_up",
"high_priority",
"requires_review"
],
"example": "urgent_attention"
}
}
},
"StationIdsFilter": {
"name": "station_ids[]",
"in": "query",
"description": "Filter by providers/stations (e.g., Dr. Samuel Johnson)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"ServiceIdsFilter": {
"name": "service_ids[]",
"in": "query",
"description": "Filter by services (e.g., General Consultation, Blood Test)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"ClientIdsFilter": {
"name": "client_ids[]",
"in": "query",
"description": "Filter by patients/clients ('All' for no filter)",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
},
"DateFromFilter": {
"name": "date_from",
"in": "query",
"description": "Start date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-01-01"
}
},
"DateToFilter": {
"name": "date_to",
"in": "query",
"description": "End date (YYYY-MM-DD)",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2025-07-25"
}
},
"SearchFilter": {
"name": "search",
"in": "query",
"description": "Search term for patient name, form content, or reference",
"required": false,
"schema": {
"type": "string",
"example": "John"
}
},
"CategoryIdsFilter": {
"name": "category_ids[]",
"in": "query",
"description": "Filter by Categories ",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
}
}
},
"securitySchemes": {
"ClientBookingSession": {
"type": "apiKey",
"description": "Booking session token obtained from the /booking/info/{bookingCode} endpoint",
"name": "X-Booking-Session",
"in": "header"
},
"PeBookingSession": {
"type": "apiKey",
"description": "Booking session token obtained from the /booking/info/{bookingCode} endpoint",
"name": "X-Booking-Session",
"in": "header"
},
"bearerAuth": {
"type": "http",
"description": "Enter JWT Bearer token in format: Bearer {token}",
"bearerFormat": "JWT",
"scheme": "bearer"
},
"apiAuth": {
"type": "http",
"description": "Login with email and password to get the authentication token",
"name": "Token based Based",
"in": "header",
"bearerFormat": "JWT",
"scheme": "bearer"
}
}
},
"tags": [
{
"name": "Space Booking - Team Members",
"description": "Manage team members / guests for the spaces feature"
},
{
"name": "Admin Booking",
"description": "Admin booking endpoints for creating bookings on behalf of clients with form preview and skip functionality"
},
{
"name": "Authentication",
"description": "User authentication endpoints including registration, login, email verification, and password reset"
},
{
"name": "2FA",
"description": "Two-factor authentication endpoints for enhanced security"
},
{
"name": "Automation",
"description": "API Endpoints for automation management"
},
{
"name": "Banners",
"description": "API Endpoints for managing banners"
},
{
"name": "Business Categories",
"description": "Business category management endpoints"
},
{
"name": "Business Partners",
"description": "Endpoints for managing business partner relationships"
},
{
"name": "Business Simple Data",
"description": "Lightweight endpoints for dropdowns and filters"
},
{
"name": "Patient Experience Analytics",
"description": "API endpoints for patient experience analytics and ratings dashboard"
},
{
"name": "Patient Experience",
"description": "API endpoints for patient experience"
},
{
"name": "Walk-in Settings",
"description": "Manage walk-in settings for organization, location, or station levels"
},
{
"name": "Onboarding",
"description": "Organization onboarding endpoints for creating and managing organization profiles"
},
{
"name": "Chat",
"description": "Chat system endpoints for authenticated users (station providers)"
},
{
"name": "Patient Chat",
"description": "Chat system endpoints for unauthenticated clients"
},
{
"name": "Client Authentication",
"description": "Client-facing authentication endpoints for user registration, login, and verification"
},
{
"name": "Client Portal",
"description": "Client portal security and session management endpoints"
},
{
"name": "Client Scheduling",
"description": "Client-facing public booking API endpoints for managing appointment scheduling flow"
},
{
"name": "Client Booking",
"description": "Client-facing public booking API endpoints for managing booking information and flow"
},
{
"name": "Client Feedback Forms",
"description": "Client-facing feedback form API endpoints"
},
{
"name": "Client Booking V3",
"description": "Patient Experience Booking API endpoints for client-side booking flow"
},
{
"name": "Forms",
"description": "Form management endpoints"
},
{
"name": "FormResponses",
"description": "Form response management endpoints"
},
{
"name": "Health Check",
"description": "System health and monitoring endpoints"
},
{
"name": "Providers",
"description": "Provider (Station) management endpoints"
},
{
"name": "PublicForms",
"description": "Public form endpoints for clients (no authentication or organization required)"
},
{
"name": "Referral Partners",
"description": "Endpoints for managing referral partner relationships"
},
{
"name": "Referral Services",
"description": "Endpoints for managing referral services"
},
{
"name": "Referral Settings",
"description": "Endpoints for managing referral partner relationships"
},
{
"name": "Referrals",
"description": "Referral form submission management endpoints for partner businesses"
},
{
"name": "Role Permissions",
"description": "API Endpoints for managing role permissions"
},
{
"name": "Booking Link Requests",
"description": "API endpoints for managing booking link requests with workspace selections and client assignments"
},
{
"name": "Schedule Links",
"description": "Generate and manage custom schedule links for organizations, locations, and stations"
},
{
"name": "Team Members",
"description": "API Endpoints for team member management"
},
{
"name": "Validation",
"description": "Validation endpoints"
},
{
"name": "Clients",
"description": "Client management endpoints"
},
{
"name": "SSO",
"description": "Single Sign-On authentication endpoints"
},
{
"name": "Queue Management",
"description": "Queue management endpoints for managing bookings, queue positions, notifications, and queue operations"
},
{
"name": "Client Attributes",
"description": "Client Attributes"
},
{
"name": "Patient Attribute Settings",
"description": "Patient Attribute Settings"
},
{
"name": "Client Categories",
"description": "Client Categories"
},
{
"name": "Conditional Forms",
"description": "Conditional Forms"
},
{
"name": "Conditional Category Configs",
"description": "Conditional Category Configs"
},
{
"name": "Client Import",
"description": "Client Import"
},
{
"name": "Client Table Settings",
"description": "Client Table Settings"
},
{
"name": "Custom Intakes",
"description": "Custom Intakes"
},
{
"name": "Patient Experience Settings",
"description": "Patient Experience Settings"
},
{
"name": "PII Redaction Settings",
"description": "PII Redaction Settings"
},
{
"name": "User Notifications",
"description": "User Notifications"
},
{
"name": "Logs",
"description": "Logs"
},
{
"name": "Validation Settings",
"description": "Validation Settings"
},
{
"name": "Organization",
"description": "Organization"
},
{
"name": "Organization Display",
"description": "Organization Display"
},
{
"name": "Domain",
"description": "Domain"
},
{
"name": "Contact Us",
"description": "Contact Us"
},
{
"name": "File",
"description": "File"
},
{
"name": "Reports",
"description": "Reports"
},
{
"name": "LocationStation",
"description": "LocationStation"
},
{
"name": "PatientIntakes",
"description": "PatientIntakes"
},
{
"name": "Analytics",
"description": "Analytics"
},
{
"name": "Role Permission v2 Team Member Configs",
"description": "Role Permission v2 Team Member Configs"
},
{
"name": "Role Permission v2 Runtime Checks",
"description": "Role Permission v2 Runtime Checks"
},
{
"name": "Role Permissions v2 Settings",
"description": "Role Permissions v2 Settings"
},
{
"name": "Role Permission v2 - Team members",
"description": "Role Permission v2 - Team members"
},
{
"name": "Service",
"description": "Service"
},
{
"name": "Station",
"description": "Station"
},
{
"name": "User Profile",
"description": "User Profile"
}
]
}