Background Processing

Long-running operations such as bulk imports are processed asynchronously using Celery background tasks. When you submit a request to an async endpoint, the API immediately returns a background_task_uuid that you can use to track progress and retrieve results.

Do you need this page? If your import is small and you want the result in the same request, use processing_mode=sync instead of polling. See QR Bulk Import v2 and Appointments Bulk Import.

Webhooks? Background-import completion is not yet available as a webhook event — continue polling the task status endpoint. Once subscribed events are extended, see Webhooks for delivery details.

Sync vs Async

	Sync	Async (background)
Response	`200` with the full result inline	`202` with a `background_task_uuid` to poll
Result delivery	Immediately, in the same request	Later — poll the task status endpoint, or check the task list
Best for	Small payloads, quick imports, callbacks that need the result now	Large files/uploads, imports that can take minutes

Both modes share the same import business logic — only the delivery timing differs. Endpoints that support sync mode expose a processing_mode parameter (background default | sync).

Async Flow — Bulk Import Walkthrough

The following example walks through a QR code address bulk import from submission to completion.

Step 1: Submit a bulk import

Send a POST request to the async endpoint. The request body is a JSON array of records to import.

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 '[
    {
      "location": "123 Main Street, Melbourne VIC 3000",
      "organization_uuid": "org-uuid-here",
      "type": "SITE",
      "name": "Main Office",
      "qr_code_name": "Front Door QR",
      "qr_code_external_reference_id": "ref-001"
    }
  ]'

Step 2: API accepts the task

The API immediately responds with 202 Accepted and a background_task_uuid. Save this UUID — you will use it to poll for status.

json

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

Step 3: Poll for completion

Poll the task status endpoint periodically. A reasonable interval is every 2-5 seconds.

curl

curl -H "Authorization: Bearer your_api_key:your_api_secret" \
  http://staging.didyougo.com.au/api/background-tasks/uuid/DEF789GHI012JKL345MNOP

While the task is running, the response shows PROCESSING with an incremental progress percentage:

json

{
  "uuid": "DEF789GHI012JKL345MNOP",
  "status": "PROCESSING",
  "progress": 45.0,
  "task_type": "IMPORT",
  "results": null,
  "error_message": null,
  ...
}

When the task completes, the status changes to COMPLETED and results contains the summary:

json

{
  "uuid": "DEF789GHI012JKL345MNOP",
  "status": "COMPLETED",
  "progress": 100.0,
  "task_type": "IMPORT",
  "results": {
    "qr_code_inserted": 2,
    "qr_code_restored": 0,
    "qr_code_tags_created": 2,
    "excluded_qr_codes": []
  },
  "error_message": null,
  ...
}

Step 4: Download error report

If the results contain excluded records, download the full error report:

curl

curl -H "Authorization: Bearer your_api_key:your_api_secret" \
  http://staging.didyougo.com.au/api/qrcodes/bulk/DEF789GHI012JKL345MNOP/errors

Task Status Endpoint

GET /api/background-tasks/uuid/{background_task_uuid}

Returns the current state of a background task.

Response Fields

Field	Type	Description
`uuid`	string	Background task UUID
`task_id`	string	Celery task ID
`task_type`	string	Task type (e.g. `IMPORT`)
`status`	string	Current status: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`
`progress`	float	Progress percentage (0.0 — 100.0)
`created_by_uuid`	string	User who created the task
`metadata`	object	Additional Information
`organization_uuid`	string	Organization the task belongs to
`results`	object	Summary of successes, failures, and excluded records
`error_message`	string	Error details if the task failed
`created_on`	string	Task creation timestamp (ISO 8601)
`updated_on`	string	Last update timestamp (ISO 8601)

List Tasks for an Organization

GET /api/background-tasks?organization_uuid={uuid}

Query Parameters

Parameter	Type	Required	Description
`organization_uuid`	string	Yes	UUID of the organization
`task_type`	string	No	Filter by task type (e.g. `QR_IMPORT`)
`page`	integer	No	Page number (default: `1`)
`per_page`	integer	No	Items per page (default: `10`)

Response Fields

Field	Type	Description
`items`	array	List of background task objects — see Task Status Endpoint for field details
`total`	integer	Total number of matching tasks across all pages
`pages`	integer	Total number of pages
`page`	integer	Current page number
`per_page`	integer	Number of items returned per page

Error Reports

Task-specific endpoints provide downloadable error reports. See the relevant resource documentation:

Appointments — Import Error Report
QR Code Addresses v2 — GET /api/qrcodes/bulk/{background_task_uuid}/errors

Possible Statuses

Status	Meaning
`PENDING`	Task is queued and waiting for a worker
`PROCESSING`	Task is currently being executed
`COMPLETED`	Task finished successfully — check `results` for details
`FAILED`	Task failed — check `error_message` for details

Example Request

curl

curl -H "Authorization: Bearer your_api_key:your_api_secret" \
  http://staging.didyougo.com.au/api/background-tasks/uuid/DEF789GHI012JKL345MNOP

Try It

Try it

Authorization Required

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

API Response

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

Example Response

json

{
  "uuid": "DEF789GHI012JKL345MNOP",
  "task_id": "celery-task-id-here",
  "task_type": "IMPORT",
  "status": "PROCESSING",
  "progress": 45.0,
  "organization_uuid": "org-uuid-here",
  "created_by_uuid": "DGSE3535DGLLD2",
  "metadata": null,
  "results": null,
  "error_message": null,
  "created_on": "2025-01-15T10:30:00Z",
  "updated_on": "2025-01-15T10:30:45Z"
}

List Tasks — Example Request

curl

curl -H "Authorization: Bearer your_api_key:your_api_secret" \
  "http://staging.didyougo.com.au/api/background-tasks?organization_uuid=org-uuid-here&task_type=QR_IMPORT&page=1&per_page=10"

Try It

Try it

Authorization Required

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

Query Parameters

API Response

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

List Tasks — Example Response

json

{
  "items": [
    {
      "uuid": "bGnVk98PngfWcgULrQFQ25",
      "task_id": "8bab1926-8129-4d1f-8f41-9aaeaddfad47",
      "task_type": "QR_IMPORT",
      "status": "COMPLETED",
      "progress": 0.0,
      "organization_uuid": "Po5fQfUGec5ucKFeMDes24",
      "created_by_uuid": "EJNedn6epaEnrcpswZHBuH",
      "metadata": {
        "filename": "qr_address_import_template (8).csv",
        "import_type": "qr_code_bulk_v2",
        "source": "file_upload"
      },
      "results": {
        "inserted": 1,
        "excluded": 0,
        "excluded_data": []
      },
      "error_message": null,
      "created_on": "2026-08-04T07:49:01.221923Z",
      "updated_on": "2026-08-04T07:49:02.164746Z"
    },
    {
      "uuid": "APsgQFjBsyJa9DWiLdPtKw",
      "task_id": "2ed5b890-0a13-41de-961f-b5eb24cee5a4",
      "task_type": "QR_IMPORT",
      "status": "COMPLETED",
      "progress": 0.0,
      "organization_uuid": "Po5fQfUGec5ucKFeMDes24",
      "created_by_uuid": "EJNedn6epaEnrcpswZHBuH",
      "metadata": {
        "filename": "qr_address_import_template (5).csv",
        "import_type": "qr_code_bulk_v2",
        "source": "file_upload"
      },
      "results": {
        "inserted": 0,
        "excluded": 1,
        "excluded_data": [
          {
            "index": 0,
            "error": "We couldn't find this address. Please check that the street address, suburb, state, postcode and country are correct.",
            "row": {
              "location": "..." ,
              "address_line_1": "...",
              "suburb": "...",
              "state": "...",
              "postcode": "...",
              "country": "..."
            }
          }
        ]
      },
      "error_message": null,
      "created_on": "2026-08-03T06:07:59.544843Z",
      "updated_on": "2026-08-03T06:07:59.616254Z"
    }
  ],
  "total": 228,
  "pages": 23,
  "page": 1,
  "per_page": 10
}