Bulk Import v2

POST /api/qrcodes/bulk

Import QR code addresses asynchronously (or synchronously — see processing_mode below). The endpoint accepts either a JSON array (same fields as v1) or a file upload (CSV or Excel). In background mode (default) it enqueues a Celery task and immediately returns a task ID with background_task_uuid for status polling. In sync mode it processes the records in the request and returns the result directly.

Processing Mode

Both modes run the same import logic and return the same result shape — the only difference is when you receive it.

Mode	How to select	Response	Use when
`background` (default)	Omit the parameter	`202` + `background_task_uuid` to poll	Large imports or when you don't need the result immediately
`sync`	JSON: `?processing_mode=sync` — File: form field `processing_mode=sync`	`200` + full result inline	Small imports when you want the result in the same request

Tip: If you don't need to process in the background, choose sync to avoid polling the Background Processing endpoints.

Request Body — JSON

Send a JSON array of objects. Each item has the same fields as Bulk Import v1:

Parameter	Type	Required	Description
`address_line_1`	string	Yes	Street address
`address_line_2`	string	No	Unit / Apartment
`suburb`	string	Yes	Suburb or city
`state`	string	Yes	State or province
`postcode`	string	Yes	Postal code
`country`	string	Yes	Country name
`location`	string	No	Full location string — overrides/drives the lookup when provided
`latitude`	float	No	Latitude coordinate
`longitude`	float	No	Longitude coordinate
`organization_uuid`	string	Yes	UUID of the organization
`type`	string	Yes	Type: `SITE` or `CLIENT_HOME`
`name`	string	No	Name or label for the QR code address
`qr_code_name`	string	Yes	Client name (or client-facing label) printed/associated with the QR code
`qr_code_external_reference_id`	string	Yes	Unique client identifier within your system

Request Body — File

Upload a CSV or Excel file (multipart/form-data):

Parameter	Type	Required	Description
`file`	file	Yes	CSV (.csv) or Excel (.xlsx) file containing QR code address records
`organization_uuid`	string	Yes	UUID of the organization

Example — JSON

json

[
  {
    "address_line_1": "123 Main Street",
    "address_line_2": "Suite 4",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000",
    "country": "Australia",
    "organization_uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "type": "SITE",
    "name": "Main Office",
    "qr_code_name": "Front Door QR",
    "qr_code_external_reference_id": "ref-001"
  }
]

See Errors & Rate Limits for the common error contract used across the API.

Error Codes

Status	Meaning
400	Bad Request — missing file, invalid payload, or duplicate locations
401	Unauthorized
403	Access Denied or subscription required
500	Internal Server Error

Example Request — JSON

curl

curl -X POST http://staging.didyougo.com.au/api/qrcodes/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key:your_api_secret" \
  -d '[
  {
    "address_line_1": "123 Main Street",
    "address_line_2": "Suite 4",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000",
    "country": "Australia",
    "organization_uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "type": "SITE",
    "name": "Main Office",
    "qr_code_name": "Front Door QR",
    "qr_code_external_reference_id": "ref-001"
  }
]'

Try It

Try it

Authorization Required

Requests are sent without cookies — you must provide a valid Bearer <api_key>:<api_secret> header.

Query Parameters

Request Body JSON

API Response

Click the Send API Request button above and see the response here!

Example Request — File

curl

curl -X POST http://staging.didyougo.com.au/api/qrcodes/bulk \
  -H "Authorization: Bearer your_api_key:your_api_secret" \
  -F "file=@qrcodes.xlsx" \
  -F "organization_uuid=org-uuid-here"

Note: The Try It console supports both JSON and file upload (multipart) modes.

Try It

Try it

Authorization Required

Requests are sent without cookies — you must provide a valid Bearer <api_key>:<api_secret> header.

Multipart Form

qrcodes.xlsx Browse

API Response

Click the Send API Request button above and see the response here!

Example Response (Background)

json

{
  "task_id": "celery-task-id-here",
  "status": "processing",
  "background_task_uuid": "QRS123TUV456WXY789ZABC"
}

Poll /api/background-tasks/uuid/{background_task_uuid} until the status is COMPLETED or FAILED. See Background Processing for the full flow.

Example Request — Sync

curl

curl -X POST "http://staging.didyougo.com.au/api/qrcodes/bulk?processing_mode=sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key:your_api_secret" \
  -d '[
  {
    "address_line_1": "123 Main Street",
    "address_line_2": "Suite 4",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000",
    "country": "Australia",
    "organization_uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "type": "SITE",
    "name": "Main Office",
    "qr_code_name": "Front Door QR",
    "qr_code_external_reference_id": "ref-001"
  }
]'

Example Response (Sync)

json

{
  "qrcode_addresses_upserted": [
    {
      "address_line_1": "123 Main Street",
      "address_line_2": "Suite 4",
      "suburb": "Melbourne",
      "state": "VIC",
      "postcode": "3000",
      "country": "Australia",
      "organization_uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "type": "SITE",
      "name": "Main Office",
      "qr_code_name": "Front Door QR",
      "qr_code_external_reference_id": "ref-001"
    }
  ],
  "qrcode_addresses_excluded": []
}

qrcode_addresses_excluded contains one entry per rejected row with its index, error, and row — use it immediately instead of downloading an error report. qrcode_addresses_upserted contains one entry per imported record (with organization_uuid included). In background mode, the task's results only store the counts (inserted, excluded) and excluded_data.