Device numbers

A device number is a SIM card you own, in an Android phone running the clearance.rest numbers app. The app forwards every SMS the SIM receives to your project, so you read them exactly like those of any other number with GET /numbers/sms/wait.

Connect a SIM

1. Install the app. Download the APK from the console (Numbers, then Device) on an Android phone with the SIM inserted. The link is also returned by the claim endpoints below as apk_url.

2. Verify the number. In the app, enter the phone number. We send a verification code to it by SMS and the app confirms it.

3. Scan the QR code. In the app, open the QR scanner and scan a code from your project. The number is then connected to the project.

The console shows a self-refreshing QR code under Numbers, then Device. From your own code you have two options, both authenticated with your API key. The SDKs wrap them as numbers.deviceClaim and numbers.deviceClaimTicket.

A single-use QR code

POST /numbers/device/claim/rest returns a token that is valid for 30 seconds and can be used once.

curl -X POST https://api.clearance.rest/numbers/device/claim/rest \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "label": "Office SIM" }'

{ "success": true, "token": "...", "expires_at": "...", "qr_payload": "clearance-rest-numbers://claim?token=...", "apk_url": "https://..." }

Render qr_payload as a QR code. With "preview": true the QR code is returned as an SVG image. label is a name shown for the connection.

A self-refreshing QR code

POST /numbers/device/claim/ticket returns a one-time mobile_claim_ticket, valid for 60 seconds. Open a WebSocket to /numbers/device/claim/socket?mobile_claim_ticket=<ticket>; the server pushes JSON events:

Event	Meaning
session	The socket is ready (session_id, ttl_ms).
qr	A fresh QR code (token, qr_payload, issued_at, expires_at). A new one arrives every 30 seconds.
scanned	The app scanned the code.
assigned	The number is connected. The socket then closes.
error	Something failed (code, message).

A text message ping is answered with pong.

Billing

• Connecting charges the first month; the number then renews monthly. Moving a device number to another project of the same team within its paid month does not charge again.
• Every SMS the SIM forwards is charged.
• Current prices are on Pricing.

If the balance cannot cover a renewal, the number is disconnected: its SMS are no longer forwarded and a number.renewal_failed event is sent. Connecting it again charges the first month again.

Status

A device item has a device object:

{ "carrier_name": "Example Mobile", "present": true, "verified_at": "...", "last_seen_at": "...", "online": true }

The phone reports regularly. When it stops, the status becomes OFFLINE; when the app reports the SIM was removed, it becomes SIM_REMOVED. Each change emits number.status_changed.

Disconnect

POST /numbers/items/{id}/release, or Release in the console, disconnects the number from the project and stops the monthly charge. You can connect the same SIM to a project again later.