API reference
The SMSFabric API is a JSON REST API. Every endpoint on these pages is public and versioned under /v1.
Base URL
Section titled “Base URL”https://api.smsfabric.comEvery request uses HTTPS. Request and response bodies are JSON with camelCase fields, except CSV exports and file uploads.
Authentication
Section titled “Authentication”Send an API key in the X-Api-Key header:
curl https://api.smsfabric.com/v1/devices \ -H "X-Api-Key: sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Each entry shows the scope it needs next to the path. Entries marked user token only refuse API keys with 403 api_key_not_allowed; use the portal for them. See Authentication.
Conventions
Section titled “Conventions”| Topic | Rule |
|---|---|
| Ids | Strings with a type prefix: msg_, evt_, dev_, sim_, pool_, ver_, con_, grp_, imp_, tpl_, cmp_, blk_, key_, whk_, dlv_, aud_, org_, usr_. |
| Timestamps | ISO 8601 in UTC, such as 2026-11-19T10:15:02.114Z. |
| Phone numbers | E.164, such as +201001234567, validated with libphonenumber. |
| Unknown fields | Rejected with 400 validation_failed. |
| Other organizations | An id that belongs to another organization returns 404 not_found, the same as one that doesn’t exist. |
| Body size | JSON bodies up to 100 KB. |
| Created | POST that creates returns 201 with the object. Actions return 200 or 202. DELETE returns 204 with no body. |
Errors
Section titled “Errors”Errors are application/problem+json:
{ "type": "https://docs.smsfabric.com/errors/not_found", "title": "Not Found", "status": 404, "detail": "Message not found", "code": "not_found", "requestId": "req_u7x0a3d6g9j2m5p8s1v4y7b0"}Every code is listed in Errors.
Pagination
Section titled “Pagination”List endpoints take limit (1 to 200, default 50) and cursor, and return { "data": [...], "nextCursor": "…" | null }. See Pagination.
Idempotency
Section titled “Idempotency”Create endpoints accept an Idempotency-Key header (1 to 255 characters of A–Z a–z 0–9 _ - : .). A retry with the same key within 24 hours gets the original response with Idempotent-Replayed: true. See Idempotency.
Rate limits
Section titled “Rate limits”Your plan’s rate per API key (60 to 6,000 requests per minute), 300 per signed-in user, 600 per IP, 1,200 per organization, and 20 per minute on bulk operations. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. See Rate limits.
Postman and Insomnia
Section titled “Postman and Insomnia”To try these endpoints without writing code, import a ready-made collection. Postman and Insomnia explains the import and the variables.
- Download the Postman collection (
smsfabric.postman_collection.json, Collection v2.1) - Download the Insomnia collection (
smsfabric.insomnia.json, v4 export)
22 ready requests in the order you'd try them, from the first send to campaigns, webhooks and your plan.
Resources
Section titled “Resources”| Resource | Endpoints |
|---|---|
| Messages | Send, list, read, stats and CSV export. |
| Verifications | One-time codes and their protection settings. |
| Devices | Paired phones, their SIMs and pairing tokens. |
| Pools | Groups of phones with round robin and failover. |
| Contacts | People you send to, with tags, custom fields and consent. |
| Contact groups | Static lists of contacts. |
| Contact imports | CSV import in two steps. |
| Templates | Reusable bodies with variables. |
| Campaigns | Bulk sends with pacing, quiet hours and reports. |
| Blacklist | Numbers that never receive messages. |
| API keys | Create, rotate and revoke keys. |
| Webhooks | Endpoints, deliveries, replays and tests. |
| Organization | Organization profile, members and invitations. |
| Plans | The price list, and your plan, limits and usage. |
| Preferences | Pacing, default SIM, send window, forwarding and time zone. |
| Audit log | Security and configuration events. |
| Health | Service status. |