Skip to content

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.

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.
POST/v1/devices/pairing-tokensdevices:manage

Creates 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.

Terminal window
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"
}
GET/v1/devicesdevices:read

Returns every paired phone, oldest first, in one page (nextCursor: null).

Terminal window
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
}
GET/v1/devices/:iddevices:read

Returns one device with its SIMs. 404 not_found if it isn’t paired to your organization.

Terminal window
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.

PATCH/v1/devices/:iddevices:manage

Renames, 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.
Terminal window
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.
DELETE/v1/devices/:iddevices:manage

Removes 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).

Terminal window
curl -X DELETE https://api.smsfabric.com/v1/devices/dev_m4p7s2v5y8b1e4h7k0n3q6t9 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
PATCH/v1/devices/:id/sims/:simIddevices:manage

Changes 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.
Terminal window
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
}
POST/v1/devices/:id/sims/:simId/defaultdevices:manage

Makes this SIM the organization’s default for messages sent without deviceId, simId or poolId. Returns 200 with the SIM (isDefault: true).

Terminal window
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.