Bulk QR creations

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}

null

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}

null

The GetQR API is in beta and is available to selected workspaces. Details may change before the general release.

A bulk creation turns a list of names and URLs into website QR codes with one shared design. It runs in the background: start it, poll its progress, then download the ZIP archive.

Method	Path	Description
`GET`	`/api/v1/bulk-qr-creations`	Get the current bulk creation
`POST`	`/api/v1/bulk-qr-creations`	Create from JSON
`POST`	`/api/v1/bulk-qr-creations/csv`	Create from a CSV file
`GET`	`/api/v1/bulk-qr-creations/{id}`	Get a bulk creation
`DELETE`	`/api/v1/bulk-qr-creations/{id}`	Abort a bulk creation
`GET`	`/api/v1/bulk-qr-creations/{id}/download`	Download the archive

How it works

Start the bulk creation

Send your rows with Create from JSON or Create from a CSV file. The API answers 202 with the bulk creation and its id.

Poll its progress

Call Get a bulk creation every few seconds until status is completed or failed.

Download the archive

When status is completed, call Download the archive to get a ZIP of the QR code images.

Limit. Up to 100 rows per bulk creation.
One at a time. Only one bulk creation runs per workspace. Starting another while one is running returns the running one.
Idempotency. Every request needs an idempotencyKey. Repeating a request with the same key and the same body returns the bulk creation already started. The same key with a different body returns 422.
Rows. Each row needs a name and a url. See Rows.
Plan. Bulk creation isn’t available on the Single QR plan: the request returns 403 exceeded_limit.

Rows

Name. Becomes the QR code’s title. Trimmed and cut to 40 characters. Repeated names (ignoring case) get a number: Menu, Menu 2, Menu 3.
URL. Becomes the destination. It must be an http or https address with a real domain, such as example.com/menu, and contain no spaces. A URL without a scheme gets https://.
Empty rows. Rows with neither a name nor a URL are skipped. A row with only one of them is rejected.

Every QR code is a website QR code on a short link. See QR types.

Headers

string

required

Bearer followed by your API key. See Authentication.

string

application/json for Create from JSON, multipart/form-data for Create from a CSV file.

The bulk creation object

string

ID of the bulk creation, for example cm2k7x9qb0003ax8eb4f6gh2t.

string

queued, processing, packaging or completed. A failed or aborted bulk creation goes through rollingBack to failed.

string

Name of the source file.

integer

Number of rows.

integer

QR codes created so far.

integer

QR code images rendered so far.

integer

Overall progress, 0 to 100. Creating takes up to 40, rendering up to 90, packaging is 95, and completed is 100.

boolean

true when a running bulk creation hasn’t made progress for 2 minutes. Keep polling: Get a bulk creation restarts a stalled bulk creation.

object | null

When status is failed: code and message. An aborted bulk creation has the code cancelled_by_user. A failed bulk creation is rolled back, so none of its QR codes are kept.

string | null

Path of Download the archive, once status is completed.

string

Start date, ISO 8601.

string

Last update date, ISO 8601.

string | null

Completion date, ISO 8601.

string | null

Failure date, ISO 8601.

Get the current bulk creation

GET /api/v1/bulk-qr-creations Returns the bulk creation still running in your workspace. When none is running, it returns the latest finished one (completed or failed) until it’s dismissed: downloading its archive or dismissing it in the dashboard does that. Otherwise it returns null. Use it to resume tracking after a restart.

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}

null

Create from JSON

POST /api/v1/bulk-qr-creations Starts a bulk creation from a list of rows. Answers 202 Accepted. The bulk creation runs in the background.

object[]

required

QR codes to create, up to 100. Each row is { "name": "...", "url": "..." } and takes no other fields. See Rows.

object

required

Design applied to every QR code: styles, frameOptions and logoOptions, all optional. Send {} for the default design. Other fields are rejected. See Customization.

string

required

Name shown in the dashboard and used for the archive, 1 to 255 characters.

string

required

Your own key for this bulk creation, 8 to 100 characters.

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Menu", "url": "https://example.com/menu" },
      { "name": "Wine list", "url": "example.com/wine" }
    ],
    "design": { "styles": { "dotsOptions": { "type": "rounded" } } },
    "sourceFilename": "campaign-links.csv",
    "idempotencyKey": "campaign-2026-08-14"
  }'

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}

Create from a CSV file

POST /api/v1/bulk-qr-creations/csv Same as Create from JSON, but takes the rows as a CSV file sent as multipart/form-data. Answers 202 Accepted. The file must be a .csv of at most 1,000,000 bytes. Its header row must be exactly name,url, followed by up to 100 data rows. See CSV format.

file

required

The CSV file.

string

required

The design object, serialized as JSON, for example {"styles":{"dotsOptions":{"type":"rounded"}}}. Send {} for the default design.

string

required

Your own key for this bulk creation, 8 to 100 characters.

string

Name shown in the dashboard and used for the archive, up to 255 characters. Defaults to the uploaded file’s name.

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "[email protected]" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"

name,url
Menu,https://example.com/menu
Wine list,example.com/wine

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}

Get a bulk creation

GET /api/v1/bulk-qr-creations/{id} Returns the status and progress of a bulk creation. Poll it while status is queued, processing or packaging. downloadUrl appears once the archive is ready.

string

required

ID of the bulk creation. Take it from the create or current-bulk-creation response.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "completed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 50,
  "renderedCount": 50,
  "percent": 100,
  "stalled": false,
  "error": null,
  "downloadUrl": "/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download",
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:02:10.000Z",
  "completedAt": "2026-08-14T08:02:10.000Z",
  "failedAt": null
}

Abort a bulk creation

DELETE /api/v1/bulk-qr-creations/{id} Stops a running bulk creation and deletes the QR codes it already created. The rollback runs during the request, so the response normally has status failed and error.code cancelled_by_user. Aborting a bulk creation that has already failed returns it unchanged.

A bulk creation that has completed can’t be aborted: the request returns 400. Delete its QR codes one by one with QR codes instead.

string

required

ID of the bulk creation.

curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "failed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": {
    "code": "cancelled_by_user",
    "message": "Bulk QR creation was cancelled."
  },
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:40.000Z",
  "completedAt": null,
  "failedAt": "2026-08-14T08:00:40.000Z"
}

Download the archive

GET /api/v1/bulk-qr-creations/{id}/download Returns a ZIP archive with one 1024 px JPEG per QR code, named after its row: 001-Menu.jpg, 002-Wine list.jpg and so on. The archive is named after sourceFilename. Available once status is completed. Downloading dismisses the bulk creation, so Get the current bulk creation stops returning it.

string

required

ID of the bulk creation.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>

Common issues

422 with "contains an invalid HTTP(S) URL"

The message names the row. Each URL must be an http or https address with a real domain, such as example.com/menu. Fix the row and send the request again.

422 "CSV headers must be exactly: name,url."

The first row of the CSV must be name,url, in that order and in lowercase, with no other columns.

422 "This idempotencyKey was already used with a different request body."

Keys can’t be reused for a different batch. Send a new idempotencyKey.

409 "The bulk QR archive is not ready for download."

The bulk creation hasn’t completed yet. Keep polling until status is completed.

400 "Cannot cancel a finished bulk QR creation."

The bulk creation has already completed, so it can’t be rolled back.

403 exceeded_limit

Your workspace is on the Single QR plan, which doesn’t include bulk creation. Upgrade the plan.

I got back an older bulk creation instead of a new one

Another bulk creation is still running in your workspace, or you reused an idempotencyKey. Wait for it to finish, or use a new key.

API

How it works

Rows

Headers

The bulk creation object

Get the current bulk creation

Create from JSON

Create from a CSV file

Get a bulk creation

Abort a bulk creation

Download the archive

Common issues

What’s next

Customization

QR codes

Bulk create in the app

CSV format

​How it works

​Rows

​Headers

​The bulk creation object

​Get the current bulk creation

​Create from JSON

​Create from a CSV file

​Get a bulk creation

​Abort a bulk creation

​Download the archive

​Common issues

​What’s next

Customization

QR codes

Bulk create in the app

CSV format

How it works

Rows

Headers

The bulk creation object

Get the current bulk creation

Create from JSON

Create from a CSV file

Get a bulk creation

Abort a bulk creation

Download the archive

Common issues

What’s next