API Documentation

Everything needed to integrate against the Connecfy API.

Authentication

Three separate credential types, none of which overlap in what they can access:

• Device token — issued at registration, sent as X-Device-Token (or Authorization: Bearer <token>). Can only act as that one device.
• Dashboard session — normal cookie-based login, used by the dashboard's own pages.
• External API key — generated from the dashboard, sent as api_key in the request body. Send-only — it can never read anything back.

No device token required — the one-time pairing code from the dashboard's Add Device screen is the credential.

curl -X POST https://your-domain.com/api/devices/register/ \
  -H "Content-Type: application/json" \
  -d '{"code":"...", "device_name":"Pixel 7", "phone_number":"+15551234567"}'

→ 201 {"device_id":"...", "device_token":"...", "device_name":"Pixel 7"}

Polled every ~20s by a paired phone. Returns queued SMS atomically claimed for that device only.

curl https://your-domain.com/api/devices/<id>/tasks/ \
  -H "X-Device-Token: <device_token>"

→ 200 [{"id":"...", "to":"+15559998888", "message":"Hello"}]

Called every ~15s — the only presence signal the backend has.

curl -X POST https://your-domain.com/api/devices/<id>/heartbeat/ \
  -H "X-Device-Token: <device_token>" -H "Content-Type: application/json" \
  -d '{"battery":81, "android_version":"14", "app_version":"1.0.0"}'

→ 200 {"status":"ok", "device_id":"...", "last_seen":"..."}

Dashboard-session authenticated. Self-managed accounts must pass device_id; API-only accounts must omit it — the platform pool handles routing.

POST /api/sms/send/
{"device_id":"...", "to":"+15551234567", "message":"Hello"}   // self-managed
{"to":"+15551234567", "message":"Hello"}                       // API-only

→ 202 {"id":"...", "status":"queued", ...}

Called by the owning device once SmsManager's sent/delivered broadcast fires.

curl -X POST https://your-domain.com/api/sms/<id>/status/ \
  -H "X-Device-Token: <device_token>" -H "Content-Type: application/json" \
  -d '{"status":"sent"}'

Send-only. No equivalent read endpoint exists for message history or device data.

curl -X POST https://your-domain.com/api/external/send/ \
  -H "Content-Type: application/json" \
  -d '{"api_key":"...", "to":"+15551234567", "message":"Hello"}'

→ 202 {"id":"...", "status":"queued"}

Dashboard-session authenticated. Global and per-device counts and success rate for the logged-in account.

curl https://your-domain.com/api/stats/ --cookie "sessionid=..."

→ 200 {"total_messages": 42, "sent": 40, "failed": 2, "success_rate": 95.2, ...}

Rate limits apply by default on send and poll endpoints — see your account settings to request higher limits.