MySim SMS · v1

API Reference

Base URL https://sms.server.fitwellhub.com

Authentication

System endpoints require a server-side API key. Never embed the key in mobile apps or public clients.

HeaderValue
X-System-Api-KeyPreferred
X-Api-KeyAccepted
AuthorizationBearer <key>
Example
curl -X PUT "https://sms.server.fitwellhub.com/api/system/sms-jobs/upsert" \
  -H "Content-Type: application/json" \
  -H "X-System-Api-Key: YOUR_SYSTEM_API_KEY" \
  -d '{ ... }'

Health

GET/health

No authentication.

StatusBody
200{ "ok": true, "service": "fitwell-msg-server" }

SMS Jobs

Enqueue SMS for a gateway user. Delivery success = job status: "acked" (not the HTTP enqueue response).

PUT/api/system/sms-jobs/upsert

Create or update a pending job by stable id (idempotent).

Body

FieldTypeRequiredNotes
idstringyesmax 128
userEmail | userIdstringone ofgateway account
tostringyes5–32 chars, E.164 preferred
messagestringyes1–1600 chars
metadataobjectnoopaque JSON
Request
{
  "id": "order-otp-1001",
  "userEmail": "gateway@clinic.com",
  "to": "+923001234567",
  "message": "Your OTP is 123456",
  "metadata": { "source": "website", "purpose": "otp" }
}
201 Created
{
  "created": true,
  "job": {
    "id": "order-otp-1001",
    "userId": "64f0a1b2c3d4e5f678901234",
    "to": "+923001234567",
    "message": "Your OTP is 123456",
    "status": "pending",
    "metadata": { "source": "website" },
    "createdAt": "2026-09-20T20:00:00.000Z",
    "updatedAt": "2026-09-20T20:00:00.000Z"
  }
}
StatusMeaning
201Created · created: true
200Updated pending · created: false
400Validation / missing owner
401Invalid API key
403User deactivated
404User not found
POST/api/system/sms-jobs

Same body as upsert; id optional (UUID if omitted).

StatusMeaning
201{ "job": {…}, "created": true }
400 401 403 404Same as upsert
GET/api/system/sms-jobs/:id
StatusBody
200{ "job": {…} }
404{ "error": "Job not found" }
PATCH/api/system/sms-jobs/:id

Update to, message, and/or metadata while status is pending.

Request
{
  "to": "+923009999999",
  "message": "Updated text"
}
StatusMeaning
200{ "job": {…}, "updated": true }
409Job not pending / not updatable

Job object

statusDescription
pendingQueued for phone
claimedLocked by device
sendingSending via SIM
ackedSuccess
failedPermanent failure
expiredTimed out

Errors

Shape
{
  "error": "Invalid payload",
  "details": { "formErrors": [], "fieldErrors": { } }
}
HTTPWhen
400Invalid body / missing userEmail|userId
401Missing/wrong API key
403Gateway user deactivated
404User or job not found
409Conflict (e.g. patch non-pending job)
500Server error

Webhooks

Per-user HTTPS callbacks. Configure in console → user → Webhooks. Delivery: POST, 8s timeout, 1 retry. Expect 2xx.

Headers

HeaderValue
Content-Typeapplication/json
User-AgentMySimSMS-Webhook/1.0
X-MySim-EventEvent name
X-MySim-Signaturehex(HMAC-SHA256(secret, rawBody)) if secret set

Envelope

{
  "event": "sms.outbound.acked",
  "at": "2026-09-20T20:15:30.123Z",
  "userId": "64f0a1b2c3d4e5f678901234",
  "data": { }
}

Events

eventURLWhen
sms.outbound.ackedOutboundSend success
sms.outbound.failedOutboundSend failure
sms.inbound.receivedInboundSIM received SMS
sms.testSameConsole test

sms.outbound.acked / failed — data

{
  "jobId": "order-otp-1001",
  "to": "+923001234567",
  "message": "Your OTP is 123456",
  "status": "acked",
  "sentAt": "2026-09-20T20:15:28.000Z",
  "ackedAt": "2026-09-20T20:15:30.000Z",
  "failedAt": null,
  "providerResult": { "ok": true },
  "error": null,
  "metadata": { "source": "website" }
}

sms.inbound.received — data

{
  "id": "66f1a2b3c4d5e6f789012345",
  "from": "+923009998877",
  "phoneNumber": "+923009998877",
  "message": "Yes, confirmed for 3pm",
  "receivedAt": "2026-09-20T21:02:10.500Z",
  "date": "2026-09-20",
  "time": "21:02:10",
  "deviceId": "android-device-abc"
}

sms.test — data

{
  "message": "MySim SMS test webhook",
  "kind": "outbound",
  "tip": "If you see this, your endpoint is reachable."
}

Catcher

POST/api/hooks/catch/:token

Temporary inbox URL from admin Webhooks panel. No auth.

200
{
  "ok": true,
  "caught": true,
  "message": "Webhook received by MySim SMS catcher",
  "at": "2026-09-20T21:05:00.000Z"
}

Postman

  1. Download collection JSON
  2. Postman → Import → file
  3. Set collection variables systemApiKey, userEmail
MySim_SMS.postman_collection.json