CandorQR REST API
Create and manage dynamic QR codes, render static QR images and read scan statistics from your own software. Machine-readable spec: /api/docs (OpenAPI 3.1; import it into Postman, Insomnia or a code generator).
Access by plan
| Plan | Endpoints | Rate limit (per key) |
|---|---|---|
| Business | Everything: create, edit, pause, delete codes; stats; static QR | 120/minute, 10,000/day |
| Pro | Read-only: list/get codes, stats; static QR images | 30/minute, 1,000/day |
| Free | No API access (use the free web generator) | n/a |
Why: write access lets one integration create hundreds of codes, which fits Business limits (500 codes, bulk). Pro users can still pull stats into their own reports and render images.
Authentication
Create a key in Dashboard → API keys. The full key is shown once; we store only a SHA-256 hash. Send it in every request:
Authorization: Bearer cq_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXUse keys only from servers. Requests over the limit get 429 with a Retry-After header. Responses include X-RateLimit-Limit and X-RateLimit-Remaining. Errors look like {"error":{"code":"invalid_key","message":"…"}}.
Quick start
# Create a dynamic code (Business)
curl -X POST https://candorqr.com/api/v1/codes \
-H "Authorization: Bearer $CANDORQR_KEY" -H "Content-Type: application/json" \
-d '{"name":"Table 12","destination":"https://example.com/menu"}'
# Change where it points later
curl -X PATCH https://candorqr.com/api/v1/codes/CODE_ID -H "Authorization: Bearer $CANDORQR_KEY" \
-H "Content-Type: application/json" -d '{"destination":"https://example.com/winter-menu"}'
# Scan stats for the last 7 days
curl "https://candorqr.com/api/v1/codes/CODE_ID/stats?days=7" -H "Authorization: Bearer $CANDORQR_KEY"
# Static QR as PNG with rounded dots and a preset logo
curl "https://candorqr.com/api/v1/qr?data=https%3A%2F%2Fexample.com&format=png&size=1024&dots=rounded&logo=instagram" \
-H "Authorization: Bearer $CANDORQR_KEY" -o qr.png
# Full designer options (gradient, eyes, frame) as vector PDF
curl -X POST https://candorqr.com/api/v1/qr -H "Authorization: Bearer $CANDORQR_KEY" -H "Content-Type: application/json" \
-d '{"data":"https://example.com","format":"pdf","widthMm":40,"design":{"dots":"classy-rounded","dotsPaint":{"type":"linear","colors":["#0b3d91","#0e7490"],"rotation":45},"eyeFrame":"extra-rounded","eyeBall":"circle","frame":{"kind":"banner","text":"SCAN ME","color":"#0b3d91","textColor":"#ffffff"}}}' -o qr.pdfEndpoints
Base URL: https://candorqr.com/api/v1
GET /me
Current key, plan and limits Pro + Business
Responses: 200 Plan, scopes and limits · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 429 Rate limit exceeded (see Retry-After)
GET /codes
List dynamic codes Pro + Business
| Parameter | In | Type | Notes |
|---|---|---|---|
limit | query | integer | default 50 |
cursor | query | string | nextCursor from the previous page |
status | query | active | paused | disabled |
Responses: 200 A page of codes · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 429 Rate limit exceeded (see Retry-After)
POST /codes
Create a dynamic code (Business) Business
JSON body: see the schema in /api/docs.
Responses: 201 Created · 400 Invalid body · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 422 Destination invalid or flagged unsafe · 429 Rate limit exceeded (see Retry-After)
GET /codes/{id}
Get a code Pro + Business
| Parameter | In | Type | Notes |
|---|---|---|---|
id * | path | string | Code id (from list/create) |
Responses: 200 The code · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 404 Not found · 429 Rate limit exceeded (see Retry-After)
PATCH /codes/{id}
Update destination, name, status or design (Business) Business
| Parameter | In | Type | Notes |
|---|---|---|---|
id * | path | string | Code id (from list/create) |
JSON body: see the schema in /api/docs.
Responses: 200 Updated · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 404 Not found · 422 Destination invalid or flagged unsafe · 429 Rate limit exceeded (see Retry-After)
DELETE /codes/{id}
Delete a code (Business) Business
| Parameter | In | Type | Notes |
|---|---|---|---|
id * | path | string | Code id (from list/create) |
Responses: 204 Deleted · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 404 Not found · 429 Rate limit exceeded (see Retry-After)
GET /codes/{id}/stats
Scan statistics Pro + Business
| Parameter | In | Type | Notes |
|---|---|---|---|
id * | path | string | Code id (from list/create) |
days | query | integer | default 30 |
Responses: 200 Stats (no personal data: country + device type per day only) · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 404 Not found · 429 Rate limit exceeded (see Retry-After)
GET /qr
Render a static QR image (simple options) Pro + Business
| Parameter | In | Type | Notes |
|---|---|---|---|
data * | query | string | Text or URL to encode |
format | query | png | svg | pdf | eps | default png |
size | query | integer | PNG width in px |
widthMm | query | number | PDF/EPS physical width |
fg | query | string | |
bg | query | string | |
dots | query | square | rounded | extra-rounded | classy | classy-rounded | dots | diamond | vertical | horizontal | |
eyeFrame | query | square | rounded | extra-rounded | circle | leaf | dots | |
eyeBall | query | square | rounded | circle | leaf | diamond | |
ec | query | L | M | Q | H | |
margin | query | integer | |
transparent | query | boolean | |
logo | query | instagram | facebook | whatsapp | linkedin | x | youtube | tiktok | email | phone | wifi | location | link | star | menu | |
frame | query | none | banner | banner-top | box | pill | |
frameText | query | string |
Responses: 200 Image · 400 Missing/too long data or bad format · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 429 Rate limit exceeded (see Retry-After)
POST /qr
Render a static QR image (full designer options) Pro + Business
JSON body: see the schema in /api/docs.
Responses: 200 Image · 400 Invalid input · 401 Missing, invalid or revoked API key · 402 Plan doesn't include this · 403 Plan scope (write needs Business) or account suspended · 429 Rate limit exceeded (see Retry-After)
Design object
The same options as the web designer: dot shapes (square, rounded, fluid, classy, classy-rounded, dots, diamond, vertical/horizontal lines), eye frame and eye ball shapes and colors, solid/linear/radial gradients, transparent background, preset logos or your own PNG/JPEG (error correction switches to H automatically), frames with call-to-action text. Codes created via the API redirect through candorqr.com short links, just like codes created in the dashboard.