Create a one-off claim QR

POST

/providers/mobile/claim/rest

const url = 'https://api.clearance.rest/numbers/providers/mobile/claim/rest?preview=false';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'},
  body: '{"label":"example","preview":false}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.clearance.rest/numbers/providers/mobile/claim/rest?preview=false' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "label": "example", "preview": false }'

Creates a single-use token, and the QR payload that carries it, for attaching a phone’s SIM to your project. Whoever holds the phone scans the QR in the SIM Bridge app, which decides which number is attached; you cannot name the number in advance.

The token is consumed on use and expires after 30 seconds. That is too short for a person to act on by hand, so for real use prefer the claim socket (GET /providers/mobile/claim/socket), which rotates the QR for you.

With preview=true the response is the QR as an image/svg+xml image instead of JSON, handy for a quick check. A preview still consumes the token.

Authorizations

ApiKey

Parameters

Query Parameters

preview

boolean

Same as the preview body field.

Request Body

application/json

object

label

Your own note about this claim. Does not affect the token.

string

preview

Return the QR as an SVG image instead of JSON.

boolean

Responses

200

The token and QR payload, or the QR image with preview=true.

object

success

required

boolean

token

required

string format: uuid

expires_at

required

When the token expires, in milliseconds since the Unix epoch.

integer

qr_payload

required

The string to render as a QR code.

string

Example

{
  "success": true,
  "token": "50ed3e0e-ffe6-4b2b-92a7-4e2cb184c258",
  "expires_at": 1786088259951,
  "qr_payload": "clearance-rest-numbers://claim?token=50ed3e0e-ffe6-4b2b-92a7-4e2cb184c258&base=https%3A%2F%2Fapi.clearance.rest%2Fnumbers"
}

401

The X-API-Key header is missing or invalid.

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Example

{
  "success": false,
  "error": "geçersiz API anahtarı"
}