get-sms-summary

Get SMS Summary (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/sms/summary

Description

Returns SMS usage summary for a workspace: message counts, total cost, payments, and remaining balance.

Backend Path

The backend is mounted at /v1/workspace/:workspaceId/sms/summary.

Authentication

Required: Workspace authentication (JWT in Authorization header)

Persona Access:

• Admin: Not applicable (workspace-scoped endpoint)
• Workspace Owner: Allowed (root persona for workspace features)
• Staff: Allowed (role-based)
• Customer: Not allowed

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Response 200 OK

{
  "totalMessages": 28,
  "sentMessages": 28,
  "failedMessages": 0,
  "pendingMessages": 0,
  "totalCost": 1.74,
  "totalPaid": 115.00,
  "remainingBalance": 113.26,
  "costPerMessage": 0.06,
  "charsPerMessage": 100,
  "minimumAllowedBalance": -0.12
}

Response Fields

• totalMessages (number): Total number of SMS records.
• sentMessages (number): Number of sent messages.
• failedMessages (number): Number of failed messages.
• pendingMessages (number): Number of pending messages.
• totalCost (number): Total cost of all SMS (sum of message.cost).
• totalPaid (number): Total amount paid for SMS.
• remainingBalance (number): Remaining balance (totalPaid - totalCost). Can be negative (debt).
• costPerMessage (number): Cost per SMS segment.
• charsPerMessage (number): Number of characters per segment used for pricing.
• minimumAllowedBalance (number): Minimum allowed balance before blocking SMS sending.

Common Errors

• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: User does not have permission to view SMS data
• 404 Not Found: Workspace not found
• 500 Internal Server Error: Server error occurred while processing the request