Skip to main content

Send SMS (Bulk Job) (v1)

Method & Path​

POST /api/v1/workspace/:workspaceId/sms/bulk-send

Description​

Creates a bulk SMS job and returns immediately with jobId. Delivery happens in the background (messages are sent one-by-one to the provider).

Authentication​

Required: Workspace auth.

Persona Access:

  • Workspace Owner: Allowed
  • Staff (role-based): Requires sms.send
  • Customer(client): Not allowed

Headers​

  • Authorization: Bearer <workspaceToken>
  • Content-Type: application/json
  • X-Staff-Id: <staffId> (optional; required when acting as Staff)

Path Parameters​

NameTypeRequiredDescription
workspaceIdstringYesWorkspace ID

Request Body​

{
  "text": "رسالة جماعية",
  "recipients": {
    "mobiles": ["+970599000000", "+972590000000"],
    "clientIds": ["66f0..."],
    "referralIds": ["66f1..."],
    "groupIds": ["66f2..."]
  }
}

Response 201 Created​

{
  "jobId": "66f3...",
  "status": "queued"
}

Common Errors​

  • 400 Bad Request: Invalid identifiers
  • 401 Unauthorized: Missing/invalid workspace token
  • 403 Forbidden: Staff missing sms.send
  • 422 Unprocessable Entity: Validation failed / insufficient balance
  • 500 Internal Server Error: Unexpected error