QR code API and webhooks
The CirculateQR REST API lets your software work with QR codes. On Artisan, keys are read-only: list codes and read a code’s details and scan analytics. On Stealth, keys can also create codes, batch-create up to 1,000 in one request, change destinations and delete codes. Requests use an API key sent as a Bearer token.
Webhooks send a signed POST to your server on every scan, with the code, destination, device, operating system, browser, country, city and time, so you can feed scans into a CRM, a spreadsheet, or Zapier and Make. Failed deliveries are retried with increasing delays.
Keys, endpoints and webhooks
Create a key
In Settings. Artisan accounts can create up to 10 read-only keys, Stealth up to 50 read and write keys. Keys can be given an expiry date and are stored only as a hash.Call the API
Send requests to /api/v1 with your key in the Authorization header.Add a webhook
In Settings → Webhooks, enter your URL and send a test event.Verify signatures
Each delivery carries an X-CQR-Signature header, an HMAC-SHA256 of the timestamp and body made with your webhook secret.
POST https://www.circulateqr.com/api/v1/qr/create
Authorization: Bearer cqr_live_…
Content-Type: application/json
{
"destination": "https://example.com/spring",
"name": "Spring poster",
"type": "DYNAMIC",
"rules": {
"ios": "https://apps.apple.com/…",
"android": "https://play.google.com/…"
}
}Endpoints
GET /api/v1/qr/list
List your codes, with paging and search by name.
GET /api/v1/qr/{id}
A code’s details, including total scans and routing rules.
GET /api/v1/qr/{id}/analytics
Scans by device, OS, country and browser, a daily trend and recent scans, for 7, 30 or 90 days or all time within your plan’s history. Bots excluded.
POST /api/v1/qr/create
Stealth. A static or dynamic code with your colors, optional iPhone and Android links, and your own metadata.
POST /api/v1/qr/batch
Stealth. Up to 1,000 codes in one request, with a result for each item.
PATCH and DELETE /api/v1/qr/{id}
Stealth. Change a code’s destination, name or status, or remove it.
Webhook deliveries
Signed with HMAC-SHA256, retried with increasing delays from 30 seconds to 2 hours, and switched off after 10 failures in a row.
Monthly quotas
10,000 requests a month on Artisan and 100,000 on Stealth.
What each plan includes
There is no CSV bulk upload in the dashboard; bulk creation is through the API on Stealth.
API access
- StandardFree
- —
- Studio$12/mo
- —
- Artisan$39/mo
- Read-only
- Stealth$149/mo
- Read and write
API requests a month
- StandardFree
- —
- Studio$12/mo
- —
- Artisan$39/mo
- 10,000
- Stealth$149/mo
- 100,000
Batch create
- StandardFree
- —
- Studio$12/mo
- —
- Artisan$39/mo
- —
- Stealth$149/mo
- Up to 1,000 per request
Webhook endpoints
- StandardFree
- 1
- Studio$12/mo
- 5
- Artisan$39/mo
- 25
- Stealth$149/mo
- 100
| StandardFree | Studio$12/mo | Artisan$39/mo | Stealth$149/mo | |
|---|---|---|---|---|
| API access | — | — | Read-only | Read and write |
| API requests a month | — | — | 10,000 | 100,000 |
| Batch create | — | — | — | Up to 1,000 per request |
| Webhook endpoints | 1 | 5 | 25 | 100 |
Annual billing saves about 20%. Full plan comparison
Where it's useful
Product packaging →
Create a code per product line from your own catalog system.
Direct mail →
Generate a code per mailing segment and pull scans back into your reports.
Asset tracking →
Create labels for new equipment as it’s added to your records.
Shipping labels →
Point label codes at tracking or returns pages and update them in bulk.
Frequently asked questions
Which plans include the API?
Artisan includes read-only API access with 10,000 requests a month. Stealth includes read and write access with 100,000 requests a month. The free and Studio plans don’t include API keys.
How many codes can I create at once?
Up to 1,000 per batch request on the Stealth plan. Each item in the batch gets its own result, so one bad row doesn’t fail the rest.
Is there a Zapier integration?
There is no CirculateQR app in Zapier. Use a webhook: point it at a Zapier or Make “catch hook” URL and every scan arrives as an event you can route anywhere.
Can the API create AI art codes?
No. API codes are standard PNG codes with your colors and the highest error-correction level. AI art is made in Studio.
How are webhooks secured?
Each delivery is signed with HMAC-SHA256 over the timestamp and body using your webhook secret, sent in the X-CQR-Signature header, so you can reject requests that didn’t come from CirculateQR.
Related
Related pages
Guides
Other features
Get an API key
Create a key in Settings on Artisan or Stealth and make your first request.