QR API

QR endpoints exposed by the Devotel CPaaS API Base path: /api/v1/qr Endpoint count: 3

Worked QR samples

The endpoint list below documents every operation’s parameters; this overlay walks a QR render the way a checkout or loyalty integration actually uses it: render the JSON envelope → save the PNG binary → branch on the script-scheme rejection. Success envelopes are { data, meta } when you ask for JSON (format=json), and raw binary when you let the default image/png content-type carry the pixels — see How to read a worked sample. Rendering runs fully in-cluster — the payload never leaves the platform. Every response carries meta.request_id. Quote it when you report a render the SDK will not link to, or a phone number that failed the normalization the SMS route applies.

1. Render a QR for arbitrary data, returned as a JSON envelope

Pass format=json to get the base64 data URL inside the standard { data, meta } envelope instead of raw PNG bytes:

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/qr/generate?data=https%3A%2F%2Fbrand.example%2Fcheckin%2Ftoken&format=json" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/qr/generate?data=https%3A%2F%2Fbrand.example%2Fcheckin%2Ftoken&format=json",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "data": "https://brand.example/checkin/token",
    "size": 300
  },
  "meta": {
    "request_id": "req_qr_generate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

2. Save the QR as a raw PNG

Omit format (or pass format=png) and the route streams image/png bytes straight to disk — useful for batch print jobs and attach-to-CDN pipelines:

cURL

curl -X GET -H "Accept: image/png" \
  "https://api.orbit.devotel.io/api/v1/qr/generate?data=https%3A%2F%2Fbrand.example%2Fcheckin%2Ftoken" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -o checkin-qr.png

The output is square; the size query param (50–1024, default 300) sets the edge length.
Responses are cacheable for five minutes (private, max-age=300), so a CDN between you and the API can serve repeat scans without a re-render.

3. Deep-link a QR to the native SMS composer

GET /api/v1/qr/sms encodes an sms:<phone>?body=… deep link — scanning it opens the device’s native SMS composer addressed to the given number with an optional pre-filled body. The number is validated and normalised to E.164 before render.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/qr/sms?phone=%2B14155552671&body=I%20want%20to%20rebook&format=json" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/qr/sms?phone=%2B14155552671&body=I%20want%20to%20rebook&format=json",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "sms_link": "sms:+14155552671?body=I%20want%20to%20rebook",
    "phone": "+14155552671",
    "size": 300
  },
  "meta": {
    "request_id": "req_qr_sms",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}

The envelope echoes the exact sms_link encoded into the QR, plus the normalised E.164 phone — pass a national-format number and the route returns the same envelope with E.164 applied.
A 400 fires when the phone is undialable under the numbering plan; the rejected input is echoed back, not stored.

4. Click-to-chat a WhatsApp conversation from a QR

GET /api/v1/qr/whatsapp encodes a https://wa.me/<phone>?text=… click-to-chat deep link — scanning it opens a WhatsApp chat with the given number and an optional pre-filled message. Same envelope shape as the SMS route, so a checkout scanner picks the channel by preference and renders the data URL inline:

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/qr/whatsapp?phone=%2B14155552671&text=Hi%20I%20want%20a%20demo&format=json" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

200

{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "whatsapp_link": "https://wa.me/14155552671?text=Hi%20I%20want%20a%20demo",
    "phone": "14155552671",
    "size": 300
  },
  "meta": {
    "request_id": "req_qr_wa",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

The whatsapp_link is the exact deep link encoded into the QR — paste it into a <a href> for an SMS-fallback path when the scanner strips wa.me.
phone is echoed in bare-digit form (no +), matching the seeded recipient string wa.me itself renders.

5. Errors

Errors follow the { error, meta } envelope. The failure every integrator builds a branch for: 400 — script-scheme rejection. A payload starting with javascript:, data:, vbscript: or another pseudo-scheme never reaches the renderer, so a misrouted user gesture cannot become a stored XSS in someone’s scanner; plain text and http(s) URLs still encode:

400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "QR data must not use script-execution URL schemes.",
    "status": 400
  },
  "meta": {
    "request_id": "req_qr_err",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}

Generate a QR code for arbitrary data

GET /api/v1/qr/generate

Render a QR code for any text or URL payload. Returns image/png bytes by default, or a base64 data URL in the standard envelope when format=json. Script-execution URL schemes (javascript:, data:, vbscript:, …) are rejected with 400; rendering runs fully in-cluster — the payload never leaves the platform.

string

required

Payload to encode (plain text or a URL, max 2048 chars). Must not start with a script-execution URL scheme such as javascript: or data:.

integer

Image edge length in pixels (50–1024, default 300). The output PNG is always square.

string (enum: png|json)

png (default) returns raw image/png bytes; json returns the standard envelope with data.qr_data_url as a base64 data URL.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/qr/generate" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/qr/generate', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/qr/generate", headers=headers)
print(r.json())

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	orbit "github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil {
		panic(err)
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	var result map[string]any
	if err := client.Request(ctx, "GET", "/qr/generate", nil, nil, &result, ""); err != nil {
		fmt.Fprintf(os.Stderr, "orbit: %v\n", err)
		os.Exit(1)
	}
	fmt.Println(result)
}

Ruby

require 'orbit_sdk'

client = OrbitSdk::Client.from_env('ORBIT_API_KEY')

result = client.request('GET', '/qr/generate')
puts result

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv('ORBIT_API_KEY');

$result = $client->request('GET', '/qr/generate');
echo json_encode($result);

{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "data": "https://brand.example/checkin/token",
    "size": 300
  },
  "meta": {
    "request_id": "req_qr_generate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Generate an SMS deep-link QR code

GET /api/v1/qr/sms

Render a QR code that encodes an sms:<phone>?body=… deep link: scanning it opens the device’s native SMS composer addressed to the given number with an optional pre-filled body. The phone number is validated and normalised to E.164 before encoding. Returns image/png bytes by default, or a base64 data URL in the standard envelope when format=json.

string

required

Destination phone number in international format (e.g. +15551234567). Rejected with 400 when it is not a dialable international number.

string

Optional pre-filled message body for the deep link (max 1024 chars). URL-encoded into the encoded wa.me / sms: payload.

integer

Image edge length in pixels (50–1024, default 300). The output PNG is always square.

string (enum: png|json)

png (default) returns raw image/png bytes; json returns the standard envelope with data.qr_data_url as a base64 data URL.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/qr/sms" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/qr/sms', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/qr/sms", headers=headers)
print(r.json())

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	orbit "github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil {
		panic(err)
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	var result map[string]any
	if err := client.Request(ctx, "GET", "/qr/sms", nil, nil, &result, ""); err != nil {
		fmt.Fprintf(os.Stderr, "orbit: %v\n", err)
		os.Exit(1)
	}
	fmt.Println(result)
}

Ruby

require 'orbit_sdk'

client = OrbitSdk::Client.from_env('ORBIT_API_KEY')

result = client.request('GET', '/qr/sms')
puts result

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv('ORBIT_API_KEY');

$result = $client->request('GET', '/qr/sms');
echo json_encode($result);

{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "data": "https://brand.example/checkin/token",
    "size": 300
  },
  "meta": {
    "request_id": "req_qr_generate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Generate a WhatsApp click-to-chat QR code

GET /api/v1/qr/whatsapp

Render a QR code that encodes a https://wa.me/<phone>?text=… click-to-chat deep link: scanning it opens a WhatsApp chat with the given number and an optional pre-filled message. The phone number is validated as a dialable international number before encoding. Returns image/png bytes by default, or a base64 data URL in the standard envelope when format=json.

string

required

Destination phone number in international format (e.g. +15551234567). Rejected with 400 when it is not a dialable international number.

string

Optional pre-filled message body for the deep link (max 1024 chars). URL-encoded into the encoded wa.me / sms: payload.

integer

Image edge length in pixels (50–1024, default 300). The output PNG is always square.

string (enum: png|json)

png (default) returns raw image/png bytes; json returns the standard envelope with data.qr_data_url as a base64 data URL.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/qr/whatsapp" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/qr/whatsapp', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/qr/whatsapp", headers=headers)
print(r.json())

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	orbit "github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil {
		panic(err)
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	var result map[string]any
	if err := client.Request(ctx, "GET", "/qr/whatsapp", nil, nil, &result, ""); err != nil {
		fmt.Fprintf(os.Stderr, "orbit: %v\n", err)
		os.Exit(1)
	}
	fmt.Println(result)
}

Ruby

require 'orbit_sdk'

client = OrbitSdk::Client.from_env('ORBIT_API_KEY')

result = client.request('GET', '/qr/whatsapp')
puts result

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv('ORBIT_API_KEY');

$result = $client->request('GET', '/qr/whatsapp');
echo json_encode($result);

{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "data": "https://brand.example/checkin/token",
    "size": 300
  },
  "meta": {
    "request_id": "req_qr_generate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

API Reference

All Endpoints

QR API

QR API

Worked QR samples

1. Render a QR for arbitrary data, returned as a JSON envelope

2. Save the QR as a raw PNG

3. Deep-link a QR to the native SMS composer

4. Click-to-chat a WhatsApp conversation from a QR

5. Errors

Generate a QR code for arbitrary data

Generate an SMS deep-link QR code

Generate a WhatsApp click-to-chat QR code

​QR API

​Worked QR samples

​1. Render a QR for arbitrary data, returned as a JSON envelope

​2. Save the QR as a raw PNG

​3. Deep-link a QR to the native SMS composer

​4. Click-to-chat a WhatsApp conversation from a QR

​5. Errors

​Generate a QR code for arbitrary data

​Generate an SMS deep-link QR code

​Generate a WhatsApp click-to-chat QR code

QR API

Worked QR samples

1. Render a QR for arbitrary data, returned as a JSON envelope

2. Save the QR as a raw PNG

3. Deep-link a QR to the native SMS composer

4. Click-to-chat a WhatsApp conversation from a QR

5. Errors

Generate a QR code for arbitrary data

Generate an SMS deep-link QR code

Generate a WhatsApp click-to-chat QR code