{ "openapi": "3.1.0", "info": { "title": "Sweeppea API v3", "version": "3.0.0", "description": "Complete REST API for managing sweepstakes, participants, winners, rules, notes, calendar events, billing, and more. All endpoints require Bearer token authentication via the Authorization header. Base URL: https://api-v3.sweeppea.com", "contact": { "name": "Sweeppea Support", "url": "https://www.sweeppea.com" }, "license": { "name": "Proprietary", "url": "https://www.sweeppea.com" } }, "externalDocs": { "description": "Full API Documentation", "url": "https://apidocs.sweeppea.com/" }, "servers": [ { "url": "https://api-v3.sweeppea.com", "description": "Production server" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Token", "description": "API token obtained from your Sweeppea account. Include as: Authorization: Bearer YOUR_API_TOKEN" } }, "schemas": { "SuccessResponse": { "type": "object", "properties": { "Response": { "type": "boolean", "example": true }, "Message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "Response": { "type": "boolean", "example": false }, "Message": { "type": "string" } } }, "Pagination": { "type": "object", "properties": { "Page": { "type": "integer" }, "Limit": { "type": "integer" }, "Total": { "type": "integer" }, "TotalPages": { "type": "integer" } } }, "Sweepstakes": { "type": "object", "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "UserToken": { "type": "string", "format": "uuid" }, "SweepstakesName": { "type": "string" }, "SweepstakesType": { "type": "integer", "description": "1=SMS, 2=Email, 3=Social" }, "Handler": { "type": "string", "maxLength": 20 }, "Settings": { "type": "object" }, "Notes": { "type": "array", "items": { "type": "object" } }, "AdminChecklist": { "type": "array", "items": { "type": "object" } }, "Score": { "type": "integer" }, "Archived": { "type": "boolean" }, "Status": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" } } }, "Participant": { "type": "object", "properties": { "ParticipantToken": { "type": "string", "format": "uuid" }, "UserToken": { "type": "string", "format": "uuid" }, "SweepstakesToken": { "type": "string", "format": "uuid" }, "KeyEmail": { "type": "string", "format": "email" }, "KeyPhoneNumber": { "type": "string" }, "FirstName": { "type": "string" }, "LastName": { "type": "string" }, "BonusEntries": { "type": "integer" }, "CreationDate": { "type": "string", "format": "date-time" }, "Status": { "type": "boolean" }, "Collection": { "type": "string", "enum": ["Participants", "ParticipantsAmoe", "OptOuts"] } } }, "Winner": { "type": "object", "properties": { "ParticipantToken": { "type": "string", "format": "uuid" }, "FirstName": { "type": "string" }, "LastName": { "type": "string" }, "Email": { "type": "string", "format": "email" }, "PhoneNumber": { "type": "string" } } }, "Rule": { "type": "object", "properties": { "RulesToken": { "type": "string", "format": "uuid" }, "SweepstakesToken": { "type": "string", "format": "uuid" }, "Title": { "type": "string", "maxLength": 100 }, "Primary": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" } } }, "Note": { "type": "object", "properties": { "NoteToken": { "type": "string", "format": "uuid" }, "Title": { "type": "string", "maxLength": 100 }, "Pinned": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" } } }, "CalendarEvent": { "type": "object", "properties": { "EventToken": { "type": "string", "format": "uuid" }, "EventTitle": { "type": "string" }, "EventStartDate": { "type": "string", "format": "date-time" }, "EventEndDate": { "type": "string", "format": "date-time" }, "EventDescription": { "type": "string" }, "EventLocation": { "type": "string" }, "EventColor": { "type": "string" }, "EventAllDay": { "type": "boolean" }, "EventStatus": { "type": "boolean" }, "PrivateEvent": { "type": "boolean" }, "Completed": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" } } }, "Group": { "type": "object", "properties": { "GroupToken": { "type": "string", "format": "uuid" }, "UserToken": { "type": "string", "format": "uuid" }, "SweepstakesToken": { "type": "string", "format": "uuid" }, "GroupName": { "type": "string" }, "Primary": { "type": "boolean" }, "Locked": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" } } }, "Ticket": { "type": "object", "properties": { "TicketToken": { "type": "string", "format": "uuid" }, "CaseNumber": { "type": "string" }, "Subject": { "type": "string" }, "Priority": { "type": "string", "enum": ["low", "medium", "high"] }, "Status": { "type": "string", "enum": ["open", "closed"] }, "CreationDate": { "type": "string", "format": "date-time" } } } }, "responses": { "Unauthorized": { "description": "Invalid or missing Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Response": false, "Message": "Unauthorized. Invalid or missing API token." } } } }, "Forbidden": { "description": "Access denied (invalid API token, account disabled, or domain restriction)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Response": false, "Message": "Forbidden. Access denied." } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Response": false, "Message": "Resource not found." } } } }, "BadRequest": { "description": "Invalid or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Response": false, "Message": "Missing required field: SweepstakesToken." } } } }, "RateLimited": { "description": "Too many concurrent requests. Use exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Response": false, "Message": "Too many requests. Please retry later." } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "tags": [ { "name": "Account", "description": "Account profile, business info, and plan details" }, { "name": "Entry Page", "description": "Entry page fields for sweepstakes" }, { "name": "Sweepstakes", "description": "Create, manage, and control sweepstakes campaigns" }, { "name": "Participants", "description": "Add and manage sweepstakes participants" }, { "name": "Groups", "description": "Participant group management" }, { "name": "Winners", "description": "Draw and manage winners" }, { "name": "Rules", "description": "Official rules documents management" }, { "name": "Notes", "description": "Encrypted personal notes" }, { "name": "Calendar", "description": "Calendar events management" }, { "name": "Billing", "description": "Billing transactions and consumptions" }, { "name": "Wallet", "description": "Wallet transaction history" }, { "name": "Todos", "description": "To-Do task management" }, { "name": "Support", "description": "Support ticket management" }, { "name": "Help", "description": "Fetch API documentation programmatically" }, { "name": "Tools", "description": "Utility data: timezones, states, zipcodes, area codes, countries" } ], "paths": { "/account/health-check": { "post": { "tags": ["Account"], "summary": "Health Check", "description": "Verify that the API is healthy and the provided Bearer token is valid.", "operationId": "accountHealthCheck", "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "API is healthy" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/account/profile": { "post": { "tags": ["Account"], "summary": "Fetch Profile Info", "description": "Retrieve the authenticated user's profile information including personal data and account status.", "operationId": "accountProfile", "responses": { "200": { "description": "Profile data", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "UserToken": { "type": "string", "format": "uuid" }, "Nickname": { "type": "string" }, "Email": { "type": "string", "format": "email" }, "UserType": { "type": "integer" }, "Status": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" }, "LastLogin": { "type": "string", "format": "date-time" }, "IsShopifyAccount": { "type": "boolean" }, "ProfileData": { "type": "object", "properties": { "FullName": { "type": "string" }, "MobilePhone": { "type": "string" }, "Address": { "type": "string" }, "City": { "type": "string" }, "State": { "type": "string" }, "ZipCode": { "type": "string" }, "Country": { "type": "string" }, "Avatar": { "type": "string" }, "BirthDate": { "type": "string", "format": "date-time" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/account/business": { "post": { "tags": ["Account"], "summary": "Fetch Business Info", "description": "Retrieve the authenticated user's business information.", "operationId": "accountBusiness", "responses": { "200": { "description": "Business data", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "BusinessName": { "type": "string" }, "BusinessTelephone": { "type": "string" }, "BusinessAddress": { "type": "string" }, "BusinessCity": { "type": "string" }, "BusinessState": { "type": "string" }, "BusinessZipCode": { "type": "string" }, "BusinessCountry": { "type": "string" }, "BusinessWebsite": { "type": "string" }, "EIN": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/account/plan": { "post": { "tags": ["Account"], "summary": "Fetch Plan Details", "description": "Retrieve the current subscription plan details including limits, pricing, and enabled modules. Requires a wildcard (*) domain in API domains.", "operationId": "accountPlan", "responses": { "200": { "description": "Plan details", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "PlanToken": { "type": "string", "format": "uuid" }, "Name": { "type": "string" }, "Description": { "type": "string" }, "Primary": { "type": "boolean" }, "Locked": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" }, "Settings": { "type": "object", "properties": { "ChargePerSweepstakes": { "type": "boolean" }, "Frequency": { "type": "string" }, "SubscriptionPrice": { "type": "number" }, "FixedPrice": { "type": "number" }, "CostPerGigaByte": { "type": "number" }, "ExtraCredits": { "type": "number" }, "WalletMinToDeposit": { "type": "number" }, "WalletMinToWithdraw": { "type": "number" }, "MaxSweepstakesAllowed": { "type": "integer" }, "MaxStorageSize": { "type": "integer" }, "MaxParticipantsAllowed": { "type": "integer" }, "MaxApiCallsAllowed": { "type": "integer" }, "PaidModuleCreateSweepstakes": { "type": "boolean" }, "PaidModuleCreateEntryPage": { "type": "boolean" }, "PaidModuleCreateOfficialRules": { "type": "boolean" }, "PaidModuleManageParticipants": { "type": "boolean" }, "PaidModuleSendMessages": { "type": "boolean" }, "PaidModuleDrawWinners": { "type": "boolean" }, "PaidModuleSeeReports": { "type": "boolean" }, "PaidModuleManageDomains": { "type": "boolean" }, "PaidModuleManageCoupons": { "type": "boolean" }, "PaidModuleAccessDrive": { "type": "boolean" }, "PaidModuleAccessCalendar": { "type": "boolean" }, "PaidModuleManageNotes": { "type": "boolean" }, "PaidModuleCreateSurveys": { "type": "boolean" }, "PaidModuleAccessAPI": { "type": "boolean" }, "PaidModuleManageDripMarketing": { "type": "boolean" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/entrypage/fields": { "post": { "tags": ["Entry Page"], "summary": "Fetch Entry Page Fields", "description": "Retrieve the form fields configured for a sweepstakes entry page. Use this to know the exact field names and types before adding participants.", "operationId": "entrypageFields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid", "description": "UUID v4 of the sweepstakes" } } }, "example": { "SweepstakesToken": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "Entry page fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "EntryPageToken": { "type": "string", "format": "uuid" }, "KeyEmail": { "type": "string" }, "KeyPhoneNumber": { "type": "string" }, "FormFields": { "type": "array", "items": { "type": "object", "properties": { "FieldID": { "type": "string" }, "FieldType": { "type": "string" }, "FieldName": { "type": "string" }, "FieldPlaceholder": { "type": "string" }, "FieldRequired": { "type": "boolean" }, "PrimaryField": { "type": "boolean" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sweepstakes/create": { "post": { "tags": ["Sweepstakes"], "summary": "Create Sweepstakes", "description": "Create a new sweepstakes campaign. Automatically generates an entry page, S3 folder, short links, QR codes, and a primary participant group. Also awards +3 user scoring points.", "operationId": "sweepstakesCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesName", "SweepstakesType", "Handler", "StartDate", "EndDate", "StartTime", "EndTime"], "properties": { "SweepstakesName": { "type": "string", "description": "Name of the sweepstakes" }, "SweepstakesType": { "type": "integer", "enum": [1, 2, 3], "description": "1=SMS, 2=Email, 3=Social" }, "Handler": { "type": "string", "maxLength": 20, "pattern": "^[A-Z0-9]+$", "description": "Unique alphanumeric identifier (auto-uppercased, max 20 chars)" }, "StartDate": { "type": "string", "format": "date", "description": "Start date (YYYY-MM-DD). Must be today or future." }, "EndDate": { "type": "string", "format": "date", "description": "End date (YYYY-MM-DD). Must be >= StartDate." }, "StartTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "Start time in HH:MM 24-hour format" }, "EndTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "End time in HH:MM 24-hour format" }, "CreateInCalendar": { "type": "boolean", "default": false, "description": "Auto-create calendar event" }, "SyncWithWinners": { "type": "boolean", "default": false }, "DeleteIfDeleted": { "type": "boolean", "default": false }, "DeleteIfAcctDeleted":{ "type": "boolean", "default": false } } }, "example": { "SweepstakesName": "Summer Giveaway 2026", "SweepstakesType": 2, "Handler": "SUMMER2026", "StartDate": "2026-03-01", "EndDate": "2026-03-31", "StartTime": "00:00", "EndTime": "23:59", "CreateInCalendar": true } } } }, "responses": { "200": { "description": "Sweepstakes created", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "$ref": "#/components/schemas/Sweepstakes" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/sweepstakes/clone": { "post": { "tags": ["Sweepstakes"], "summary": "Clone Sweepstakes", "description": "Clone an existing sweepstakes into a new one with a new handler, name, and dates.", "operationId": "sweepstakesClone", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["Handler", "HandlerNew", "SweepstakesName", "StartDate", "EndDate", "StartTime", "EndTime"], "properties": { "Handler": { "type": "string", "description": "Handler of the original sweepstakes to clone" }, "HandlerNew": { "type": "string", "maxLength": 20, "description": "Handler for the new cloned sweepstakes" }, "SweepstakesName": { "type": "string", "description": "Name for the new sweepstakes" }, "StartDate": { "type": "string", "format": "date" }, "EndDate": { "type": "string", "format": "date" }, "StartTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" }, "EndTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" } } } } } }, "responses": { "200": { "description": "Sweepstakes cloned", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "SweepstakesToken": { "type": "string", "format": "uuid" }, "SweepstakesType": { "type": "integer" }, "SweepstakesName": { "type": "string" }, "Handler": { "type": "string" }, "StartDate": { "type": "string", "format": "date" }, "EndDate": { "type": "string", "format": "date" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "New handler already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sweepstakes/fetch": { "post": { "tags": ["Sweepstakes"], "summary": "Fetch All Sweepstakes", "description": "Retrieve all sweepstakes belonging to the authenticated user, including full settings.", "operationId": "sweepstakesFetch", "responses": { "200": { "description": "List of sweepstakes", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Sweepstakes" } }, "Count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/sweepstakes/update": { "post": { "tags": ["Sweepstakes"], "summary": "Update Sweepstakes", "description": "Update one or more fields of an existing sweepstakes. At least one optional field must be provided.", "operationId": "sweepstakesUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "SweepstakesName": { "type": "string", "maxLength": 200 }, "StartDate": { "type": "string", "format": "date" }, "EndDate": { "type": "string", "format": "date" }, "StartTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" }, "EndTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" } } } } } }, "responses": { "200": { "description": "Sweepstakes updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "$ref": "#/components/schemas/Sweepstakes" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sweepstakes/delete": { "post": { "tags": ["Sweepstakes"], "summary": "Delete Sweepstakes", "description": "Permanently delete a sweepstakes and all associated data (participants, entry pages, statistics, groups, rules, calendar events, short links, coupons, automations).", "operationId": "sweepstakesDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sweepstakes/pause": { "post": { "tags": ["Sweepstakes"], "summary": "Pause Sweepstakes", "description": "Pause an active sweepstakes, temporarily stopping new entries.", "operationId": "sweepstakesPause", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sweepstakes/unpause": { "post": { "tags": ["Sweepstakes"], "summary": "Unpause Sweepstakes", "description": "Resume a previously paused sweepstakes.", "operationId": "sweepstakesUnpause", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Unpaused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/participants/add": { "post": { "tags": ["Participants"], "summary": "Add Participant", "description": "Add a new participant to a sweepstakes. Field names with spaces must use underscores (e.g., 'First_Name'). Use the /entrypage/fields endpoint first to get the correct field names.", "operationId": "participantsAdd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["lang", "source", "sweepstakesToken", "entryPageFields"], "properties": { "lang": { "type": "string", "example": "EN", "description": "Language code (e.g., EN)" }, "source": { "type": "string", "example": "api", "description": "Entry source identifier" }, "sweepstakesToken": { "type": "string", "format": "uuid" }, "entryPageFields": { "type": "object", "properties": { "KeyPhoneNumber": { "type": "string", "description": "Phone number (E.164 or local format)" }, "KeyEmail": { "type": "string", "format": "email" }, "BonusEntries": { "type": "integer", "default": 0, "description": "Additional entries to give this participant" }, "Fields": { "type": "object", "description": "Custom form fields. Replace spaces in field names with underscores (e.g., First_Name, Last_Name)." } } } } }, "example": { "lang": "EN", "source": "api", "sweepstakesToken": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", "entryPageFields": { "KeyEmail": "john@example.com", "KeyPhoneNumber": "+15551234567", "BonusEntries": 0, "Fields": { "First_Name": "John", "Last_Name": "Doe" } } } } } }, "responses": { "200": { "description": "Participant added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/participants/fetch": { "post": { "tags": ["Participants"], "summary": "Fetch Participants", "description": "Retrieve participants for a sweepstakes with pagination, search, and date filtering. Returns 20 results per page sorted by newest first. Searches across Participants, ParticipantsAmoe, and OptOuts collections.", "operationId": "participantsFetch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "page": { "type": "integer", "default": 1, "description": "Page number" }, "search": { "type": "string", "description": "Search term (matches FirstName, LastName, Email, Phone)" }, "optInDate": { "type": "string", "format": "date", "description": "Filter by specific opt-in date (YYYY-MM-DD)" }, "startDate": { "type": "string", "format": "date", "description": "Date range start (requires endDate)" }, "endDate": { "type": "string", "format": "date", "description": "Date range end (requires startDate)" } } } } } }, "responses": { "200": { "description": "Participants list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "Pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/participants/count": { "post": { "tags": ["Participants"], "summary": "Count Participants", "description": "Get participant counts for a sweepstakes, broken down by collection type (Participants, AMOE, OptOuts) with optional date range filtering.", "operationId": "participantsCount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "FilterType": { "type": "string", "enum": ["all", "participants", "amoe", "optouts"], "default": "all" }, "StartDate": { "type": "string", "format": "date-time" }, "EndDate": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Participant counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "FilterType": { "type": "string" }, "DateRange": { "type": "object" }, "Counts": { "type": "object", "properties": { "Participants": { "type": "integer" }, "AmoeParticipants": { "type": "integer" }, "OptOuts": { "type": "integer" }, "Total": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/participants/single": { "post": { "tags": ["Participants"], "summary": "Fetch Single Participant", "description": "Retrieve a single participant by token, email, or phone number. At least one search parameter (ParticipantToken, KeyEmail, or KeyPhoneNumber) is required.", "operationId": "participantsSingle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "ParticipantToken": { "type": "string", "format": "uuid", "description": "Search by participant token" }, "KeyEmail": { "type": "string", "format": "email", "description": "Search by email" }, "KeyPhoneNumber": { "type": "string", "description": "Search by phone number" } } } } } }, "responses": { "200": { "description": "Participant data with all entries across collections", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "SweepstakesToken": { "type": "string" }, "SweepstakesName": { "type": "string" }, "TotalEntries": { "type": "integer" }, "Collections": { "type": "array", "items": { "type": "string" } }, "Entries": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/participants/delete": { "delete": { "tags": ["Participants"], "summary": "Delete Participant", "description": "Permanently delete a participant from all collections (Participants, AMOE, OptOuts) within a sweepstakes.", "operationId": "participantsDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken", "ParticipantToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "ParticipantToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Participant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "type": "object", "properties": { "ParticipantToken": { "type": "string" }, "SweepstakesToken": { "type": "string" }, "DeletedFrom": { "type": "array", "items": { "type": "string" } }, "DeletedCount": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/groups/create": { "post": { "tags": ["Groups"], "summary": "Create Group", "description": "Create a new participant group within a sweepstakes. Group names must be unique within the sweepstakes.", "operationId": "groupsCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken", "groupName"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "groupName": { "type": "string", "description": "Unique name for this group within the sweepstakes" } } } } } }, "responses": { "200": { "description": "Group created", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "$ref": "#/components/schemas/Group" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/groups/fetch": { "post": { "tags": ["Groups"], "summary": "Fetch Groups", "description": "Retrieve all participant groups for a sweepstakes.", "operationId": "groupsFetch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Groups list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "Count": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/groups/update": { "post": { "tags": ["Groups"], "summary": "Update Group", "description": "Rename a participant group. The new name must be unique within the sweepstakes.", "operationId": "groupsUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken", "groupToken", "groupName"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "groupToken": { "type": "string", "format": "uuid" }, "groupName": { "type": "string", "description": "New unique name for the group" } } } } } }, "responses": { "200": { "description": "Group updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/groups/delete": { "post": { "tags": ["Groups"], "summary": "Delete Group", "description": "Delete a participant group. Cannot delete primary groups, locked groups, or groups that contain participants.", "operationId": "groupsDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken", "groupToken"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "groupToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Group deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/winners/draw": { "post": { "tags": ["Winners"], "summary": "Draw Winners", "description": "Randomly draw winners from eligible participants using a weighted algorithm (bonus entries increase selection probability). The sweepstakes must not be paused or archived.", "operationId": "winnersDraw", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken", "howManyWinnersToPick", "group"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "howManyWinnersToPick": { "type": "integer", "minimum": 1 }, "group": { "type": "string", "description": "Use 'allgroups' or a specific GroupToken" }, "completedEntries": { "type": "boolean", "default": false }, "includeOptedOutParticipants": { "type": "boolean", "default": false }, "doNotIncludeSpamParticipants": { "type": "boolean", "default": true } } }, "example": { "sweepstakesToken": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", "howManyWinnersToPick": 3, "group": "allgroups", "doNotIncludeSpamParticipants": true } } } }, "responses": { "200": { "description": "Winners drawn", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Winners": { "type": "array", "items": { "$ref": "#/components/schemas/Winner" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/winners/fetch": { "post": { "tags": ["Winners"], "summary": "Fetch Winners", "description": "Retrieve all drawn winners for a sweepstakes with pagination and search.", "operationId": "winnersFetch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "page": { "type": "integer", "default": 1 }, "itemsPerPage": { "type": "integer", "default": 10 }, "search": { "type": "string" } } } } } }, "responses": { "200": { "description": "Winners list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "TotalWinners": { "type": "integer" }, "Winners": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/winners/schedule": { "post": { "tags": ["Winners"], "summary": "Schedule Drawing", "description": "Schedule an automated winner drawing for a future date and time, with optional recurring frequency.", "operationId": "winnersSchedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken", "group", "selectedAction", "scheduleMode", "howManyWinnersToPick", "endDate", "endTime", "timezone"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "group": { "type": "string" }, "selectedAction": { "type": "integer", "enum": [1, 2], "description": "1=Draw only, 2=Draw & Notify" }, "scheduleMode": { "type": "string", "enum": ["schedule", "settime"] }, "howManyWinnersToPick": { "type": "integer", "minimum": 1 }, "frequency": { "type": "integer", "enum": [0, 1, 2, 3, 4], "description": "0=None, 1=Hourly, 2=Daily, 3=Weekly, 4=Monthly" }, "dayOfTheWeek": { "type": "integer", "minimum": 1, "maximum": 7, "description": "1=Sunday...7=Saturday" }, "weekOfTheMonth": { "type": "integer", "minimum": 1, "maximum": 4 }, "endDate": { "type": "string", "format": "date" }, "endTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" }, "timezone": { "type": "integer" }, "message": { "type": "string" }, "includeOptedOutParticipants": { "type": "boolean" }, "publishToWinnersPage": { "type": "boolean" }, "sendCopyToMe": { "type": "boolean" }, "doNotIncludeSpamParticipants":{ "type": "boolean" }, "addDrawingToCalendar": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Drawing scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/winners/fetchscheduled": { "get": { "tags": ["Winners"], "summary": "Fetch Scheduled Drawings", "description": "Retrieve all scheduled drawings for a sweepstakes.", "operationId": "winnersFetchScheduled", "parameters": [ { "name": "sweepstakesToken", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 of the sweepstakes" } ], "responses": { "200": { "description": "Scheduled drawings list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/winners/deletescheduled": { "delete": { "tags": ["Winners"], "summary": "Delete Scheduled Drawing", "description": "Cancel and delete a previously scheduled winner drawing.", "operationId": "winnersDeleteScheduled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sweepstakesToken", "scheduledToken"], "properties": { "sweepstakesToken": { "type": "string", "format": "uuid" }, "scheduledToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Scheduled drawing deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/rules/create": { "post": { "tags": ["Rules"], "summary": "Create Rules Document", "description": "Create an official rules document for a sweepstakes. The first document created becomes the primary rules. Subsequent documents are secondary.", "operationId": "rulesCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken", "Title", "DocumentContent"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "Title": { "type": "string", "maxLength": 100 }, "DocumentContent": { "type": "string", "maxLength": 1000000, "description": "HTML content of the rules document" } } } } } }, "responses": { "200": { "description": "Rules document created", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "$ref": "#/components/schemas/Rule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/rules/createWizard": { "post": { "tags": ["Rules"], "summary": "Create Rules (Wizard)", "description": "Create official rules using a step-by-step wizard with structured form fields. Automatically generates the rules document from template.", "operationId": "rulesCreateWizard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" }, "Title": { "type": "string" }, "WizardData": { "type": "object", "description": "Structured wizard form data for rules generation" } } } } } }, "responses": { "200": { "description": "Rules created via wizard", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/rules/fetch": { "post": { "tags": ["Rules"], "summary": "Fetch Rules", "description": "Retrieve all rules documents associated with a sweepstakes.", "operationId": "rulesFetch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["SweepstakesToken"], "properties": { "SweepstakesToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Rules list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/rules/update": { "put": { "tags": ["Rules"], "summary": "Update Rules", "description": "Update an existing rules document title or content.", "operationId": "rulesUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["RulesToken"], "properties": { "RulesToken": { "type": "string", "format": "uuid" }, "Title": { "type": "string", "maxLength": 100 }, "DocumentContent": { "type": "string", "maxLength": 1000000 } } } } } }, "responses": { "200": { "description": "Rules updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/rules/delete": { "post": { "tags": ["Rules"], "summary": "Delete Rules", "description": "Permanently delete a rules document.", "operationId": "rulesDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["RulesToken"], "properties": { "RulesToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Rules deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/notes/create": { "post": { "tags": ["Notes"], "summary": "Create Note", "description": "Create an encrypted personal note. Notes are encrypted with AES-256-CBC. Title must be unique per user.", "operationId": "notesCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["Title", "Note"], "properties": { "Title": { "type": "string", "maxLength": 100, "description": "Unique note title" }, "Note": { "type": "string", "maxLength": 100000, "description": "Note content (will be AES-256-CBC encrypted)" }, "Pinned": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "$ref": "#/components/schemas/Note" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/notes/fetch": { "get": { "tags": ["Notes"], "summary": "Fetch All Notes", "description": "Retrieve all notes for the authenticated user.", "operationId": "notesFetch", "responses": { "200": { "description": "Notes list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/notes/update": { "post": { "tags": ["Notes"], "summary": "Update Note", "description": "Update an existing note's title, content, or pinned status.", "operationId": "notesUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["NoteToken"], "properties": { "NoteToken": { "type": "string", "format": "uuid" }, "Title": { "type": "string", "maxLength": 100 }, "Note": { "type": "string", "maxLength": 100000 }, "Pinned": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Note updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/notes/delete": { "post": { "tags": ["Notes"], "summary": "Delete Note", "description": "Permanently delete a note.", "operationId": "notesDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["NoteToken"], "properties": { "NoteToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Note deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/calendar/create": { "post": { "tags": ["Calendar"], "summary": "Create Calendar Event", "description": "Create a new calendar event. Events cannot be created in the past.", "operationId": "calendarCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["EventTitle", "EventStartDate", "EventEndDate"], "properties": { "EventTitle": { "type": "string" }, "EventStartDate": { "type": "string", "format": "date-time", "description": "Must be future date" }, "EventEndDate": { "type": "string", "format": "date-time", "description": "Must be future date" }, "EventDescription": { "type": "string" }, "EventLocation": { "type": "string" }, "Latitude": { "type": "string" }, "Longitude": { "type": "string" }, "EventURL": { "type": "string" }, "EventStartTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "default": "00:00" }, "EventEndTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "default": "23:59" }, "EventColor": { "type": "string", "default": "#6CD9FF" }, "EventAllDay": { "type": "boolean", "default": false }, "EventStatus": { "type": "boolean", "default": false }, "PrivateEvent": { "type": "boolean", "default": false }, "SMSNotification": { "type": "boolean", "default": false }, "Completed": { "type": "boolean", "default": false }, "SweepstakesToken": { "type": "string", "format": "uuid" }, "PeopleInvolved": { "type": "array", "items": { "type": "object" } }, "RepeatThisEvent": { "type": "object" }, "Notification": { "type": "object" } } } } } }, "responses": { "201": { "description": "Event created", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "$ref": "#/components/schemas/CalendarEvent" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/calendar/fetch": { "get": { "tags": ["Calendar"], "summary": "Fetch Calendar Events", "description": "Retrieve all calendar events for the authenticated user.", "operationId": "calendarFetch", "responses": { "200": { "description": "Events list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/calendar/single": { "post": { "tags": ["Calendar"], "summary": "Fetch Single Event", "description": "Retrieve a single calendar event by its token.", "operationId": "calendarSingle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["EventToken"], "properties": { "EventToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Event data", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/calendar/update": { "put": { "tags": ["Calendar"], "summary": "Update Calendar Event", "description": "Update an existing calendar event.", "operationId": "calendarUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["EventToken"], "properties": { "EventToken": { "type": "string", "format": "uuid" }, "EventTitle": { "type": "string" }, "EventStartDate": { "type": "string", "format": "date-time" }, "EventEndDate": { "type": "string", "format": "date-time" }, "EventDescription": { "type": "string" }, "EventLocation": { "type": "string" }, "EventColor": { "type": "string" }, "EventAllDay": { "type": "boolean" }, "Completed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Event updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/calendar/delete": { "delete": { "tags": ["Calendar"], "summary": "Delete Calendar Event", "description": "Permanently delete a calendar event.", "operationId": "calendarDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["EventToken"], "properties": { "EventToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Event deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/billing/fetchtransactions": { "get": { "tags": ["Billing"], "summary": "Fetch Billing Transactions", "description": "Retrieve all billing transactions for the authenticated user.", "operationId": "billingFetchTransactions", "responses": { "200": { "description": "Billing transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "TotalTransactions": { "type": "integer" }, "Transactions": { "type": "array", "items": { "type": "object", "properties": { "InvoiceNumber": { "type": "string" }, "TransactionID": { "type": "string" }, "Description": { "type": "string" }, "Amount": { "type": "number" }, "AmountPrizes": { "type": "number" }, "Status": { "type": "string" }, "Refunded": { "type": "boolean" }, "IsSandboxTransaction":{ "type": "boolean" }, "DocumentType": { "type": "string" }, "CreationDate": { "type": "string", "format": "date-time" }, "ExpirationDate": { "type": "string", "format": "date-time" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/billing/consumptions": { "get": { "tags": ["Billing"], "summary": "Fetch Consumptions", "description": "Retrieve monthly and yearly consumption totals aggregated from billing transactions and data transfers.", "operationId": "billingConsumptions", "responses": { "200": { "description": "Consumption data", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "description": "Consumption totals aggregated by year and month" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/billing/datatransfer": { "post": { "tags": ["Billing"], "summary": "Fetch Data Transfer", "description": "Retrieve data transfer billing logs for the authenticated user.", "operationId": "billingDataTransfer", "responses": { "200": { "description": "Data transfer records", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/wallet/fetchtransactions": { "get": { "tags": ["Wallet"], "summary": "Fetch Wallet Transactions", "description": "Retrieve all wallet transactions (credits and debits) for the authenticated user.", "operationId": "walletFetchTransactions", "responses": { "200": { "description": "Wallet transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "object", "properties": { "TotalTransactions": { "type": "integer" }, "Transactions": { "type": "array", "items": { "type": "object", "properties": { "TransactionID": { "type": "string" }, "Description": { "type": "string" }, "CCType": { "type": "string" }, "CCLastFourDigits": { "type": "string" }, "TransactionType": { "type": "string", "enum": ["credit", "debit"] }, "Amount": { "type": "string" }, "IsSandboxTransaction": { "type": "boolean" }, "Status": { "type": "boolean" }, "CreationDate": { "type": "string", "format": "date-time" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/tickets/createTodo": { "post": { "tags": ["Todos"], "summary": "Create To-Do", "description": "Create a new To-Do task item.", "operationId": "todosCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["Title"], "properties": { "Title": { "type": "string" }, "Description": { "type": "string" }, "DueDate": { "type": "string", "format": "date" }, "Priority": { "type": "string", "enum": ["low", "medium", "high"] }, "Status": { "type": "string", "enum": ["pending", "in-progress", "completed"] } } } } } }, "responses": { "200": { "description": "To-Do created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tickets/fetchTodos": { "post": { "tags": ["Todos"], "summary": "Fetch To-Do's", "description": "Retrieve all To-Do tasks with optional filtering and pagination.", "operationId": "todosFetch", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1 }, "limit": { "type": "integer", "default": 20 }, "status": { "type": "string" }, "priority": { "type": "string" } } } } } }, "responses": { "200": { "description": "To-Do list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tickets/create": { "post": { "tags": ["Support"], "summary": "Create Support Ticket", "description": "Create a new support ticket. The ticket is automatically assigned to all admin users and receives a unique 7-digit case number.", "operationId": "ticketsCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["Subject", "Message"], "properties": { "Subject": { "type": "string" }, "Message": { "type": "string" }, "Priority": { "type": "string", "enum": ["low", "medium", "high"], "default": "medium" }, "Category": { "type": "string" } } } } } }, "responses": { "200": { "description": "Ticket created", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Message": { "type": "string" }, "Data": { "$ref": "#/components/schemas/Ticket" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tickets/fetchOpenTickets": { "post": { "tags": ["Support"], "summary": "Fetch Open Tickets", "description": "Retrieve all open support tickets for the authenticated user.", "operationId": "ticketsFetchOpen", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1 }, "limit": { "type": "integer", "default": 20 } } } } } }, "responses": { "200": { "description": "Open tickets", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tickets/fetchClosedTickets": { "post": { "tags": ["Support"], "summary": "Fetch Closed Tickets", "description": "Retrieve all closed/resolved support tickets for the authenticated user.", "operationId": "ticketsFetchClosed", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1 }, "limit": { "type": "integer", "default": 20 } } } } } }, "responses": { "200": { "description": "Closed tickets", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tickets/fetchSingleTicket": { "post": { "tags": ["Support"], "summary": "Fetch Single Ticket", "description": "Retrieve full details of a single support ticket including all notes and history.", "operationId": "ticketsFetchSingle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["TicketToken"], "properties": { "TicketToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Ticket details", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tickets/resolve": { "post": { "tags": ["Support"], "summary": "Resolve Ticket", "description": "Mark a support ticket as resolved/closed.", "operationId": "ticketsResolve", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["TicketToken"], "properties": { "TicketToken": { "type": "string", "format": "uuid" }, "Resolution": { "type": "string" } } } } } }, "responses": { "200": { "description": "Ticket resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tickets/update": { "post": { "tags": ["Support"], "summary": "Update Ticket", "description": "Add a note or update details on an existing support ticket.", "operationId": "ticketsUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["TicketToken"], "properties": { "TicketToken": { "type": "string", "format": "uuid" }, "Note": { "type": "string" }, "Priority": { "type": "string", "enum": ["low", "medium", "high"] } } } } } }, "responses": { "200": { "description": "Ticket updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tickets/delete": { "post": { "tags": ["Support"], "summary": "Delete Ticket", "description": "Permanently delete a support ticket.", "operationId": "ticketsDelete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["TicketToken"], "properties": { "TicketToken": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Ticket deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documentation/fetch": { "post": { "tags": ["Help"], "summary": "Fetch Documentation", "description": "Retrieve API documentation content programmatically for LLM integration or custom help systems.", "operationId": "documentationFetch", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Section": { "type": "string", "description": "Specific documentation section to retrieve" } } } } } }, "responses": { "200": { "description": "Documentation content", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/timezones": { "post": { "tags": ["Tools"], "summary": "Fetch Timezones", "description": "Retrieve a list of all supported timezones with their IDs and offsets.", "operationId": "toolsTimezones", "responses": { "200": { "description": "Timezones list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "type": "object", "properties": { "ID": { "type": "integer" }, "Name": { "type": "string" }, "Offset": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/states": { "post": { "tags": ["Tools"], "summary": "Fetch US States", "description": "Retrieve a list of all US states with codes and names.", "operationId": "toolsStates", "responses": { "200": { "description": "US states list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "type": "object", "properties": { "Code": { "type": "string" }, "Name": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/zipcodes": { "post": { "tags": ["Tools"], "summary": "Fetch Zip Codes", "description": "Search and retrieve US zip code data.", "operationId": "toolsZipcodes", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ZipCode": { "type": "string", "description": "Zip code to look up" }, "City": { "type": "string", "description": "City name to search" }, "State": { "type": "string", "description": "State code to filter" } } } } } }, "responses": { "200": { "description": "Zip code data", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/areacodes": { "post": { "tags": ["Tools"], "summary": "Fetch Area Codes", "description": "Retrieve US telephone area codes with associated state and region data.", "operationId": "toolsAreacodes", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "AreaCode": { "type": "string" }, "State": { "type": "string" } } } } } }, "responses": { "200": { "description": "Area codes", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/countries": { "post": { "tags": ["Tools"], "summary": "Fetch Countries", "description": "Retrieve a complete list of countries with ISO codes and names.", "operationId": "toolsCountries", "responses": { "200": { "description": "Countries list", "content": { "application/json": { "schema": { "type": "object", "properties": { "Response": { "type": "boolean" }, "Data": { "type": "array", "items": { "type": "object", "properties": { "Code": { "type": "string" }, "Name": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } } }