Devices
A device is an Android phone running the SMSFabric app and paired to your organization. Each device reports its SIMs. Messages are sent from a device and SIM; see Send messages for how one is chosen.
The device object
Section titled “The device object”| Field | Type | Description |
|---|---|---|
id |
string | dev_… |
name |
string | Your name for the phone. |
status |
string | online, offline or disabled. A phone is online while it has checked in within the last 2 minutes. |
enabled |
boolean | false when you or SMSFabric disabled it. Disabled phones get no messages. |
poolId |
string or null | The pool it belongs to. |
model, manufacturer, os, osVersion, appVersion |
string or null | Reported by the app. |
battery |
number or null | 0 to 100. |
charging |
boolean or null | |
signal |
number or null | 0 to 4 bars. |
network |
string or null | wifi, lte, 5g, 3g, 2g or none. |
lastSeenAt |
string or null | Last heartbeat. |
createdAt |
string | When it was paired. |
sims |
SIM[] | Its SIMs, by slot. |
The SIM object:
| Field | Type | Description |
|---|---|---|
id |
string | sim_… |
slot |
integer | Physical slot, from 0. |
subscriptionId |
integer | Android subscription id. |
iccidLast4 |
string or null | Last 4 digits of the ICCID. |
carrier |
string or null | Carrier name. |
number |
string or null | The SIM’s number, when the phone knows it. |
isEsim |
boolean | |
enabled |
boolean | Disabled SIMs are never used. |
dailyLimit |
integer or null | Max messages a day from this SIM. null is unlimited. |
label |
string or null | Your label. |
isDefault |
boolean | The organization’s default sending SIM. |
Create a pairing token
Section titled “Create a pairing token”/v1/devices/pairing-tokensdevices:manageCreates a one-time token for pairing a phone. Valid for 10 minutes. Show qrPayload as a QR code for the app to scan, or enter the token by hand. Supports Idempotency-Key. Audited as device.pairing_token_created. See Pair a phone.
curl -X POST https://api.smsfabric.com/v1/devices/pairing-tokens \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "qrPayload": "smsfabric://pair?server=https%3A%2F%2Fapi.smsfabric.com&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "expiresAt": "2026-11-19T10:25:00.000Z"}List devices
Section titled “List devices”/v1/devicesdevices:readReturns every paired phone, oldest first, in one page (nextCursor: null).
curl https://api.smsfabric.com/v1/devices \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "name": "Pixel 8 · front desk", "status": "online", "enabled": true, "poolId": "pool_c6f9j2m5p8s1v4y7b0e3h6k9", "model": "Pixel 8", "manufacturer": "Google", "os": "android", "osVersion": "15", "battery": 86, "charging": true, "signal": 4, "network": "wifi", "appVersion": "1.4.0", "lastSeenAt": "2026-11-19T10:14:51.000Z", "createdAt": "2026-10-02T08:40:12.000Z", "sims": [ { "id": "sim_r2t4v6x8z1b3d5f7h9j2l4n6", "slot": 0, "subscriptionId": 1, "iccidLast4": "4417", "carrier": "Vodafone EG", "number": "+201009876543", "isEsim": false, "enabled": true, "dailyLimit": 500, "label": "Support line", "isDefault": true } ] } ], "nextCursor": null}Retrieve a device
Section titled “Retrieve a device”/v1/devices/:iddevices:readReturns one device with its SIMs. 404 not_found if it isn’t paired to your organization.
curl https://api.smsfabric.com/v1/devices/dev_m4p7s2v5y8b1e4h7k0n3q6t9 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"The response is a device object as in List devices.
Update a device
Section titled “Update a device”/v1/devices/:iddevices:manageRenames, disables or moves a phone. Audited as device.updated. Returns the device.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
name |
string | No | Display name. | 1 to 120 characters. |
enabled |
boolean | No | false stops new messages to this phone. |
|
poolId |
string or null | No | Join this pool; null leaves the current one. |
Must belong to your organization. |
curl -X PATCH https://api.smsfabric.com/v1/devices/dev_m4p7s2v5y8b1e4h7k0n3q6t9 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Pixel 8 · warehouse", "poolId": "pool_c6f9j2m5p8s1v4y7b0e3h6k9"}'| Error | When |
|---|---|
404 not_found |
The device or the pool is not in your organization. |
Unpair a device
Section titled “Unpair a device”/v1/devices/:iddevices:manageRemoves the phone from your organization and revokes its device token. The app on the phone stops sending. Messages waiting for the phone that it hasn’t taken yet move to another online phone in its pool; the rest fail with errorCode: "device_unpaired". Returns 204. Audited as device.unpaired.
The phone app does the same when you unpair it in its Settings, through the Device API (POST /device/v1/unpair).
curl -X DELETE https://api.smsfabric.com/v1/devices/dev_m4p7s2v5y8b1e4h7k0n3q6t9 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Update a SIM
Section titled “Update a SIM”/v1/devices/:id/sims/:simIddevices:manageChanges one SIM’s settings. Returns the SIM.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
enabled |
boolean | No | false stops sending from this SIM. |
|
dailyLimit |
integer or null | No | Max messages a day. null removes the limit. |
0 to 100,000. |
label |
string or null | No | Your label. | Up to 80 characters. |
curl -X PATCH https://api.smsfabric.com/v1/devices/dev_m4p7s2v5y8b1e4h7k0n3q6t9/sims/sim_r2t4v6x8z1b3d5f7h9j2l4n6 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"dailyLimit": 300, "label": "Marketing"}'{ "id": "sim_r2t4v6x8z1b3d5f7h9j2l4n6", "slot": 0, "subscriptionId": 1, "iccidLast4": "4417", "carrier": "Vodafone EG", "number": "+201009876543", "isEsim": false, "enabled": true, "dailyLimit": 300, "label": "Marketing", "isDefault": true}Set the default SIM
Section titled “Set the default SIM”/v1/devices/:id/sims/:simId/defaultdevices:manageMakes this SIM the organization’s default for messages sent without deviceId, simId or poolId. Returns 200 with the SIM (isDefault: true).
curl -X POST https://api.smsfabric.com/v1/devices/dev_m4p7s2v5y8b1e4h7k0n3q6t9/sims/sim_r2t4v6x8z1b3d5f7h9j2l4n6/default \ -H "X-Api-Key: $SMSFABRIC_API_KEY"| Error | When |
|---|---|
404 not_found |
The device or SIM is not in your organization. |