Bulk QR Creation

Bulk QR creation allows you to create hundreds or thousands of QR codes at once using CSV files. This is perfect for large marketing campaigns, product launches, or any scenario where you need to generate many QR codes efficiently.

Bulk QR Creation is available starting from Starter Plans. Upgrade your plan to create multiple QR codes efficiently and scale your campaigns.

Overview

The bulk QR creation process involves three main steps:

Upload CSV File - Upload your CSV file containing QR code data
Submit Bulk Job - Create a bulk creation job
Monitor and Download - Track job progress and download results

Step 1: Upload CSV File

First, upload your CSV file to get an asset reference. The CSV file must follow the Website QR code format.

Website QR Code CSV Format

Your CSV file should have the following structure:

CSV

QR Code Name,QR Code Description,Redirection URL
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/
Product Catalog,Product Catalog QR Code,https://example.com/catalog
Event Registration,Event Registration QR,https://example.com/register
Contact Page,Contact Information QR,https://example.com/contact

Required Columns

Column	Required	Description	Example
`QR Code Name`	Yes	The title/name for the QR code	"Company Brochure"
`QR Code Description`	Yes	Description of the QR code	"Company Brochure's QR Code 2014"
`Redirection URL`	Yes	The URL the QR code should redirect to	"http://www.example.com/promo2014/"

CSV File Requirements

File Format: CSV (Comma-Separated Values)
Encoding: UTF-8
Delimiter: Comma (,)
Header Row: Required (first row must contain column names)
File Size: Maximum 10MB
Row Limit: Maximum 1000 QR codes per file

Example CSV File

CSV

QR Code Name,QR Code Description,Redirection URL
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/
Company Brochure,Company Brochure's QR Code 2014,http://www.example.com/promo2014/

Upload the CSV File

bash

curl 'https://api.v2.qrcodekit.com/api/assets/upload' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@bulk_template_website.csv'

Response

JSON

{
  "@context": "/api/contexts/Asset",
  "@id": "/api/assets/e218025e-7f29-11f0-ba4c-46063e93b702",
  "@type": "Asset",
  "url": "https://cdn.qrcodekit.com/v2-assets/prod/vnFFfN.csv",
  "uploadType": 1,
  "extra": {
    "size": 547,
    "originalName": "bulk_template_website.csv",
    "mime": "text/csv"
  },
  "type": 1,
  "uuid": "e218025e-7f29-11f0-ba4c-46063e93b702"
}

Step 2: Submit Bulk Creation Job

Use the asset reference to create a bulk QR creation job. You can optionally assign all QR codes to a specific project:

bash

curl 'https://api.v2.qrcodekit.com/api/qrs/bulk-create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset": "/api/assets/e218025e-7f29-11f0-ba4c-46063e93b702",
    "project": "/api/projects/8a94b788-7f2a-11f0-a6f0-46063e93b702"
  }'

Creating QR Codes Without Project Assignment

If you don't want to assign the QR codes to a project, simply omit the project parameter:

bash

curl 'https://api.v2.qrcodekit.com/api/qrs/bulk-create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset": "/api/assets/e218025e-7f29-11f0-ba4c-46063e93b702"
  }'

Request Parameters

Parameter	Type	Required	Description
`asset`	string	Yes	The asset reference from the upload step
`project`	string	No	Optional project to assign all QR codes to. If provided, all QR codes in the bulk operation will be automatically assigned to this project

Response

JSON

{
  "@context": {
    "@vocab": "https://api.v2.qrcodekit.com/api/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "job": "BulkCreateQrOutput/job"
  },
  "@type": "BulkCreateQrOutput",
  "@id": "/api/.well-known/genid/3fce73cefce1d8572320",
  "job": {
    "@id": "/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702",
    "@type": "Job",
    "type": 0,
    "status": 0,
    "result": [],
    "uuid": "e2659ba4-7f29-11f0-8880-46063e93b702",
    "statusDescription": "CREATED"
  }
}

Step 3: Monitor Job Progress

Poll the job status until it completes:

bash

curl 'https://api.v2.qrcodekit.com/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID'

Job Status Responses

Job Created (Status: 0)

JSON

{
  "@context": "/api/contexts/Job",
  "@id": "/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702",
  "@type": "Job",
  "type": 0,
  "status": 0,
  "result": [],
  "uuid": "e2659ba4-7f29-11f0-8880-46063e93b702",
  "statusDescription": "CREATED"
}

Job Running (Status: 1)

JSON

{
  "@context": "/api/contexts/Job",
  "@id": "/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702",
  "@type": "Job",
  "type": 0,
  "startTime": "1755847831",
  "status": 1,
  "result": [],
  "uuid": "e2659ba4-7f29-11f0-8880-46063e93b702",
  "statusDescription": "RUNNING"
}

Job Completed (Status: 3)

JSON

{
  "@context": "/api/contexts/Job",
  "@id": "/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702",
  "@type": "Job",
  "type": 0,
  "startTime": "1755847831",
  "stopTime": "1755847837",
  "status": 3,
  "result": {
    "asset": "/api/assets/e5f47880-7f29-11f0-a7af-46063e93b702",
    "total": 6,
    "assetUrl": "https://cdn.qrcodekit.com/v2-assets/prod/account/67e93faa-a8e4-11ef-b56c-aaa69682ddc5/files/e2659ba4-7f29-11f0-8880-46063e93b702.zip"
  },
  "uuid": "e2659ba4-7f29-11f0-8880-46063e93b702",
  "statusDescription": "OK"
}

Job Status Codes

Status	Description	Action
`0`	CREATED	Job is queued and waiting to start
`1`	RUNNING	Job is currently being processed
`2`	ERROR	Job failed with an error
`3`	OK	Job completed successfully

Complete Example Workflow

Here's a complete example of creating bulk QR codes with project assignment:

bash

# Step 1: Upload CSV file
curl 'https://api.v2.qrcodekit.com/api/assets/upload' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@bulk_template_website.csv'

# Step 2: Create bulk job with project assignment (using the asset ID from step 1)
curl 'https://api.v2.qrcodekit.com/api/qrs/bulk-create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset": "/api/assets/96a340f8-7f2a-11f0-9857-46063e93b702",
    "project": "/api/projects/8a94b788-7f2a-11f0-a6f0-46063e93b702"
  }'

# Step 3: Poll job status until completion
curl 'https://api.v2.qrcodekit.com/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID'

# Step 4: Download the ZIP file with all QR codes
curl 'https://cdn.qrcodekit.com/v2-assets/prod/account/67e93faa-a8e4-11ef-b56c-aaa69682ddc5/files/e2659ba4-7f29-11f0-8880-46063e93b702.zip' \
  -o 'bulk-qr-codes.zip'

Example Without Project Assignment

If you prefer to create QR codes without assigning them to a project:

bash

# Step 2: Create bulk job without project assignment
curl 'https://api.v2.qrcodekit.com/api/qrs/bulk-create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset": "/api/assets/96a340f8-7f2a-11f0-9857-46063e93b702"
  }'

Best Practices

CSV File Preparation

Validate your data - Ensure all URLs are accessible and valid
Use descriptive names - Make QR codes easy to identify
Test with small files - Start with a few QR codes before large batches
Backup your data - Keep copies of your CSV files

Job Monitoring

Poll regularly - Check job status every 5-10 seconds
Handle errors - Implement error handling for failed jobs
Set timeouts - Don't poll indefinitely; set reasonable timeouts
Log progress - Keep track of job progress for debugging

Performance Optimization

Batch appropriately - Don't create too many QR codes in one job
Use projects - Organize QR codes into projects for better management
Monitor rate limits - Stay within API rate limits
Plan for scale - Consider the total number of QR codes you'll create

Project Organization Benefits

Automatic organization - All QR codes from a bulk operation are automatically assigned to the same project
Easy filtering - Filter and search QR codes by project
Analytics grouping - Get analytics for all QR codes in a project
Team collaboration - Share projects with team members
Bulk management - Update or delete all QR codes in a project at once

Error Handling

Common Errors

Error	Description	Solution
`Invalid CSV format`	CSV file doesn't match expected structure	Check CSV column headers and data format
`Invalid URLs`	One or more URLs in CSV are invalid	Validate all URLs before uploading
`Rate limit exceeded`	Too many requests in a short time	Implement exponential backoff
`File too large`	CSV file exceeds size limit	Split into smaller files

Error Response Example

JSON

{
  "@context": "/api/contexts/Job",
  "@id": "/api/jobs/e2659ba4-7f29-11f0-8880-46063e93b702",
  "@type": "Job",
  "type": 0,
  "startTime": "1755847831",
  "stopTime": "1755847837",
  "status": 2,
  "result": {
    "error": "Invalid CSV format",
    "message": "CSV file must contain required columns: QR Code Name, Redirection URL"
  },
  "uuid": "e2659ba4-7f29-11f0-8880-46063e93b702",
  "statusDescription": "ERROR"
}

Bulk QR Creation

Overview

Step 1: Upload CSV File

Website QR Code CSV Format

Required Columns

CSV File Requirements

Example CSV File

Upload the CSV File

Response

Step 2: Submit Bulk Creation Job

Creating QR Codes Without Project Assignment

Request Parameters

Response

Step 3: Monitor Job Progress

Job Status Responses

Job Created (Status: 0)

Job Running (Status: 1)

Job Completed (Status: 3)

Job Status Codes

Complete Example Workflow

Example Without Project Assignment

Best Practices

CSV File Preparation

Job Monitoring

Performance Optimization

Project Organization Benefits

Error Handling

Common Errors

Error Response Example

Next Steps