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.
| Header | Value |
|---|---|
X-System-Api-Key | Preferred |
X-Api-Key | Accepted |
Authorization | Bearer <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
/healthNo authentication.
| Status | Body |
|---|---|
| 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/upsertCreate or update a pending job by stable id (idempotent).
Body
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | max 128 |
userEmail | userId | string | one of | gateway account |
to | string | yes | 5–32 chars, E.164 preferred |
message | string | yes | 1–1600 chars |
metadata | object | no | opaque 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"
}
}| Status | Meaning |
|---|---|
| 201 | Created · created: true |
| 200 | Updated pending · created: false |
| 400 | Validation / missing owner |
| 401 | Invalid API key |
| 403 | User deactivated |
| 404 | User not found |
POST
/api/system/sms-jobsSame body as upsert; id optional (UUID if omitted).
| Status | Meaning |
|---|---|
| 201 | { "job": {…}, "created": true } |
| 400 401 403 404 | Same as upsert |
GET
/api/system/sms-jobs/:id| Status | Body |
|---|---|
| 200 | { "job": {…} } |
| 404 | { "error": "Job not found" } |
PATCH
/api/system/sms-jobs/:idUpdate to, message, and/or metadata while status is pending.
Request
{
"to": "+923009999999",
"message": "Updated text"
}| Status | Meaning |
|---|---|
| 200 | { "job": {…}, "updated": true } |
| 409 | Job not pending / not updatable |
Job object
| status | Description |
|---|---|
pending | Queued for phone |
claimed | Locked by device |
sending | Sending via SIM |
acked | Success |
failed | Permanent failure |
expired | Timed out |
Errors
Shape
{
"error": "Invalid payload",
"details": { "formErrors": [], "fieldErrors": { } }
}| HTTP | When |
|---|---|
| 400 | Invalid body / missing userEmail|userId |
| 401 | Missing/wrong API key |
| 403 | Gateway user deactivated |
| 404 | User or job not found |
| 409 | Conflict (e.g. patch non-pending job) |
| 500 | Server error |
Webhooks
Per-user HTTPS callbacks. Configure in console → user → Webhooks. Delivery: POST, 8s timeout, 1 retry. Expect 2xx.
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | MySimSMS-Webhook/1.0 |
X-MySim-Event | Event name |
X-MySim-Signature | hex(HMAC-SHA256(secret, rawBody)) if secret set |
Envelope
{
"event": "sms.outbound.acked",
"at": "2026-09-20T20:15:30.123Z",
"userId": "64f0a1b2c3d4e5f678901234",
"data": { }
}Events
| event | URL | When |
|---|---|---|
sms.outbound.acked | Outbound | Send success |
sms.outbound.failed | Outbound | Send failure |
sms.inbound.received | Inbound | SIM received SMS |
sms.test | Same | Console 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/:tokenTemporary 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
- Download collection JSON
- Postman → Import → file
- Set collection variables
systemApiKey,userEmail