API Reference — Connecfy

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

Authorization: Bearer YOUR_API_KEY

You can create multiple keys — one per integration — and revoke them individually without affecting others.

Send SMS

POST/api/v1/sms/send/

Queue an outbound SMS for delivery. Returns 202 Accepted immediately — the message is in the queue, not yet sent.

Request fields

Field	Type	Required	Description
to	string	Required	Recipient in E.164 format — `+212612345678`
from	string	Required	Sender number registered to your account
message	string	Required	Message body. Max 1,600 characters (~10 SMS segments)
request_id	string	Optional	Idempotency key — same key within 24h returns the original, no duplicate
send_at	ISO 8601	Optional	Schedule delivery — e.g. `2026-09-01T09:00:00Z`

curl -X POST https://connecfy.com/api/v1/sms/send/ \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+212612345678", "from": "+212600000000", "message": "Your verification code is 482910", "request_id": "order-12345" }'

import requests response = requests.post( "https://connecfy.com/api/v1/sms/send/", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "to": "+212612345678", "from": "+212600000000", "message": "Hello from Connecfy!", "request_id": "order-12345", }, ) data = response.json() msg_id = data["message_id"]

const res = await fetch("https://connecfy.com/api/v1/sms/send/", { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ to: "+212612345678", from: "+212600000000", message: "Hello from Connecfy!", request_id: "order-12345", }), }); const { message_id } = await res.json();

// 202 Accepted
{
  "status":      "queued",
  "message_id":  "f3a1b2c4-d5e6-7890-abcd-ef1234567890",
  "request_id":  "order-12345",
  "device_id":   "a8b9c0d1-...",
  "from_number": "+212600000000",
  "to":          "+212612345678",
  "created_at":  "2026-07-15T14:30:00.123Z"
}

Get message status

GET/api/v1/sms/<message_id>/

Retrieve the current status of any message queued by your account.

curl https://connecfy.com/api/v1/sms/f3a1b2c4-.../ \ -H "Authorization: Bearer YOUR_API_KEY" // 200 OK { "status": "delivered", "message_id": "..." }

Receiving SMS

Any SIM card paired to your account can receive SMS, not just send it. When a message arrives on the phone's SIM, the Connecfy app reports it automatically — no configuration needed.

Received messages show up in your dashboard's Messages view alongside sent ones, marked with a ↓ and the sender's number, in the same conversation thread as anything you've sent to or received from that number.

{
  "direction":   "inbound",
  "status":      "received",
  "from_number": "+212612345678",
  "body":        "Your appointment is confirmed",
  "received_at": "2026-08-25T09:12:04Z"
}

Current limitation: there is no public API endpoint yet to fetch received messages programmatically or to register a webhook for them — inbound SMS is currently dashboard-only. If your integration needs to react to incoming messages automatically, contact us about your use case.

Account stats

GET/api/v1/account/stats/

curl https://connecfy.com/api/v1/account/stats/ \ -H "Authorization: Bearer YOUR_API_KEY" // 200 OK { "total_messages": 847, "queued": 3, "sent": 820, "failed": 24, "success_rate": 97.2 }

Error codes

HTTP	code	Meaning
401	auth_invalid_key	API key missing, revoked, or malformed
400	(field name)	Validation failed — response body has per-field details
403	from_number_not_found	The `from` number isn't registered in your account
403	from_number_access_denied	The number exists but your account can't use it
503	device_inactive	The device linked to that number is deactivated
404	not_found	No message with that ID on your account
429	throttled	Rate limit hit — retry after the `Retry-After` header value

Status lifecycle

queued → sending → sent → delivered
               └──→ failed (auto-retry if retries remain)

queued — in the queue, waiting for a device to poll
sending — a device claimed it and is calling Android SmsManager
sent — radio confirmed transmission to the carrier
delivered — delivery receipt from recipient's network (not universal)
failed — all retries exhausted

Full Python example

import requests, time API_KEY = "YOUR_API_KEY" BASE = "https://connecfy.com/api/v1" HEADERS = {"Authorization": f"Bearer {API_KEY}"} # 1. Send result = requests.post(f"{BASE}/sms/send/", headers=HEADERS, json={ "to": "+212612345678", "from": "+212600000000", "message": "Hello!", "request_id": "unique-key-123", }).json() msg_id = result["message_id"] # 2. Poll for delivery (use exponential backoff in production) for _ in range(12): time.sleep(25) st = requests.get(f"{BASE}/sms/{msg_id}/", headers=HEADERS).json() if st["status"] in ("delivered", "failed"): break

Device API (Android app internals)

Used by the Connecfy Android app — documented here for transparency.

Method	Endpoint	Auth	Description
POST	/api/devices/register/	One-time code	Pair a new device via QR scan or typed code
GET	/api/devices/<id>/tasks/	Device token	Poll for queued messages — up to 50 per call, every ~20s
POST	/api/devices/<id>/heartbeat/	Device token	Keep-alive every 15s, includes battery level
POST	/api/v1/device/update-status/	Device token	Report sent/delivered/failed after SmsManager fires

Questions about integrating? Email contact@yassermansour.com or call +212 647 955 576