API Reference: Background Tasks

Overview

Background tasks track long-running asynchronous operations in Simply360 — bulk data imports, data exports, document generation, website copies, blueprint installs, integration syncs, and similar work. Tasks are queued and processed by dedicated workers; your client polls the task until it completes. The Background Tasks API lets you list visible tasks, inspect a task's status, progress, sanitized result, and errors, acknowledge errors, and archive finished tasks. A companion set of endpoints exposes per-record task history and downloadable record output files.

Key Concepts

• Task — One asynchronous operation, identified by a simplyId and typed by enumBackgroundTaskTypeId (for example BULK_DATA_IMPORT, DATA_EXPORT, DOCUMENT_GENERATION, WEBSITE_COPY).
• Status — Lifecycle status: QUEUED, PROCESSING, COMPLETED, FAILED, or PARTIAL_SUCCESS. completedAt is set once the task finishes.
• Errors — A task accumulates structured error rows (for example one per failed import row). Unacknowledged errors are returned on the task detail and can be acknowledged individually.
• Record outputs — Tasks that run against specific data records (such as document generation) attach typed outputs to each record. Outputs can carry a file and can be written into a destination field on the record.
• Sanitized payloads — progress, result, and error context are filtered to public display fields; internal storage, AI, render, and user identifiers are redacted.

Authentication and Tiers

Background task endpoints require user-backed first-party authentication: a Simply360 session (Cognito) or an approved first-party OAuth access token, sent as a bearer token, plus a selected team (X-Team-Id header with the team's simplyId, or a teamSimplyId query parameter). Requests authenticated with a team API key (Authorization: Bearer s360_live_...) are rejected with 403 COGNITO_REQUIRED on this surface.

Five operations are standard tier (task status reads and lightweight actions). The remaining seven are privileged tier — first-party admin and download surfaces driven by the Simply360 web app. Both tiers are listed below; the standard operations are documented in depth. See Authentication for token types and team selection.

Endpoints

Method	Path	Tier	Description
GET	/v1/background-tasks	standard	List visible background tasks for the current user and team.
GET	/v1/background-tasks/{backgroundTaskSimplyId}	standard	Get task detail with sanitized result and unacknowledged errors.
POST	/v1/background-tasks/{backgroundTaskSimplyId}/errors/{backgroundTaskErrorSimplyId}/acknowledge	standard	Acknowledge a task error.
POST	/v1/background-tasks/{backgroundTaskSimplyId}/archive	standard	Archive a task (sets clearedAt).
POST	/v1/background-tasks/{backgroundTaskSimplyId}/unarchive	standard	Unarchive a task.
POST	/v1/background-tasks	privileged	Create a background task for the current user and team.
GET	/v1/background-tasks/{backgroundTaskSimplyId}/result-download	privileged	Presign a short-lived download URL for a completed task's result file.
GET	/v1/background-tasks/record-history	privileged	List background task history for a data record.
GET	/v1/background-tasks/record-outputs/{recordOutputSimplyId}/download	privileged	Presign a per-record task output file.
GET	/v1/background-tasks/output-destinations/eligible	privileged	List eligible destination fields for a typed task output.
PUT	/v1/background-tasks/output-defaults	privileged	Create or update a team default for a typed task output.
DELETE	/v1/background-tasks/output-defaults/{defaultSimplyId}	privileged	Delete a team output default.

List Background Tasks

GET /v1/background-tasks returns the tasks visible to the current user in the selected team, newest first.

Parameter	Type	Description
limit	integer	Page size. Default 50, maximum 500.
offset	integer	Skip count for pagination.
status	string	Filter by lifecycle status (QUEUED, PROCESSING, COMPLETED, FAILED, PARTIAL_SUCCESS).
enumBackgroundTaskTypeId	string	Filter by task type.
teamIntegrationSimplyId	string	Filter to tasks scoped to one team integration. Returns 404 if the integration does not belong to the selected team.

curl -s "https://api.simply360.app/v1/background-tasks?status=PROCESSING&limit=25" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN" \
  -H "X-Team-Id: TEAM-1234-ABCD"

{
  "data": {
    "tasks": [
      {
        "simplyId": "BGTK-1234-ABCD",
        "enumBackgroundTaskTypeId": "BULK_DATA_IMPORT",
        "status": "PROCESSING",
        "progress": { "processedCount": 240, "totalCount": 1000 },
        "result": null,
        "errorCount": 2,
        "errorCountUnacknowledged": 2,
        "unacknowledgedErrorCount": 2,
        "createdAt": "2026-07-07T15:02:11.000Z",
        "startedAt": "2026-07-07T15:02:14.000Z",
        "completedAt": null,
        "lastUpdatedAt": "2026-07-07T15:03:40.000Z",
        "clearedAt": null
      }
    ],
    "canViewBackgroundTasks": true,
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

result is always null in list responses; fetch the task detail to read it.

Get a Background Task

GET /v1/background-tasks/{backgroundTaskSimplyId} returns the same fields as the list plus a sanitized result object and the task's unacknowledged errors.

curl -s "https://api.simply360.app/v1/background-tasks/BGTK-1234-ABCD" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN" \
  -H "X-Team-Id: TEAM-1234-ABCD"

The sanitized result exposes public display fields when present — for example filename, contentType, recordCount, recordsCreated, recordsUpdated, successCount, failureCount, durationMs, and a stats object for website copy jobs. Each error entry contains:

{
  "simplyId": "BGTE-5678-EFGH",
  "errorType": "ROW_VALIDATION_FAILED",
  "errorMessage": "Email address is invalid.",
  "errorContext": { "rowNumber": 41, "field": "email" },
  "acknowledgedAt": null,
  "occurredAt": "2026-07-07T15:03:12.000Z"
}

A simple polling loop:

async function waitForTask(taskSimplyId: string): Promise<unknown> {
  for (;;) {
    const res = await fetch(`https://api.simply360.app/v1/background-tasks/${taskSimplyId}`, {
      headers: {
        Authorization: `Bearer ${process.env.S360_ACCESS_TOKEN}`,
        'X-Team-Id': 'TEAM-1234-ABCD',
      },
    });
    const { data: task } = await res.json();
    if (['COMPLETED', 'FAILED', 'PARTIAL_SUCCESS'].includes(task.status)) return task;
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

Create and Download a Data Export

DATA_EXPORT is an egress boundary with a strict public-ID request contract. Its queueData accepts exactly one dataCollectionSimplyId or dataViewSimplyId, an explicit dataFieldSimplyIds array, optional safe systemColumns (CALCULATED_NAME, RECORD_SIMPLY_ID, CREATED_AT, UPDATED_AT, or APPROVAL_STATUS), an optional canonical requestFilter, and optional dataRecordSimplyIds. Physical table/column names, headers, output data types, bucket names, and object keys are server-owned and rejected from this boundary.

{
  "enumBackgroundTaskTypeId": "DATA_EXPORT",
  "queueData": {
    "dataViewSimplyId": "VIEW-1234-ABCD",
    "dataFieldSimplyIds": ["DFLD-1234-ABCD", "DFLD-5678-EFGH"],
    "systemColumns": ["RECORD_SIMPLY_ID", "CREATED_AT"],
    "dataRecordSimplyIds": []
  }
}

The server resolves the View's owning Collection, enforces protected-View access, and intersects the saved View filter, request filter, and selected-record restriction. It validates every output, predicate, and referenced-Collection field and derives approval visibility from current permission. For users restricted to approved snapshots, live calculated record names and approval status are unavailable as export columns; selected DataFields are projected from the approved snapshot. The same normalized scope and fingerprint are checked at creation, in the bounded keyset/multipart worker, and before download. A completed zero-row export is a valid header-only CSV.

Only the active initiating member can call GET /v1/background-tasks/{backgroundTaskSimplyId}/result-download for a completed export. The endpoint derives and validates the private object from the owned task, rechecks current export scope, and returns a 60-second URL plus the safe filename. It never accepts storage coordinates from the caller. Task list/detail responses expose canDownloadResult; list results never expose the URL itself.

Task Visibility

Visibility is permission-derived; the list endpoint never leaks tasks a user cannot see.

• Team Admins (and SysAdmins) see all tasks in the selected team.
• Other team users see their own user-scoped tasks — types EXTERNAL_FILE_IMPORT, IMAGE_VARIANT_GENERATION, BULK_DATA_IMPORT, DATA_EXPORT, BULK_DELETE, and DOCUMENT_GENERATION — provided they have any data access (a readable collection, a runnable DataWizard, or full data access).
• Team-visible task types are additionally shown to users holding the matching feature permission. Examples: WEBSITE_COPY, WEBSITE_TEMPLATE_RELEASE, and WEBSITE_DYNAMIC_REFRESH require a websites permission; BLUEPRINT_INSTALL / BLUEPRINT_UPGRADE / BLUEPRINT_SEED require schema administration; DUPLICATE_MERGE requires data cleanup; integration sync types require the corresponding integration permission.

The list response includes canViewBackgroundTasks so a client can hide task UI entirely for users with no visibility.

Acknowledge Errors

POST /v1/background-tasks/{backgroundTaskSimplyId}/errors/{backgroundTaskErrorSimplyId}/acknowledge marks one error as reviewed. Acknowledged errors drop out of the task detail, and the task's errorCountUnacknowledged is recomputed.

curl -s -X POST "https://api.simply360.app/v1/background-tasks/BGTK-1234-ABCD/errors/BGTE-5678-EFGH/acknowledge" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN" \
  -H "X-Team-Id: TEAM-1234-ABCD" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "success": true,
    "backgroundTaskErrorSimplyId": "BGTE-5678-EFGH",
    "acknowledgedAt": "2026-07-07T15:10:02.000Z",
    "unacknowledgedCount": 1
  }
}

Archive and Unarchive

Archiving clears a finished task from active status surfaces without deleting it. POST /v1/background-tasks/{backgroundTaskSimplyId}/archive sets clearedAt; POST .../unarchive clears it. Both accept an empty JSON object body and return { "success": true } (archive also returns the new clearedAt).

Record Task History and Outputs (Privileged)

Two privileged-tier endpoints expose the per-record view of background task work. They power the record timeline in the Simply360 app and enforce collection read permissions on the caller.

Record History

GET /v1/background-tasks/record-history?dataRecordSimplyId=WXYZ-5678-IJKL lists task runs that targeted a data record. dataCollectionSimplyId is optional; when omitted, the first collection membership the caller can read is used. Supports limit (default 25, max 100) and offset.

{
  "data": {
    "dataRecordSimplyId": "WXYZ-5678-IJKL",
    "dataCollectionSimplyId": "DCOL-9012-MNOP",
    "tasks": [
      {
        "recordTaskLinkSimplyId": "BTRL-3456-QRST",
        "backgroundTaskSimplyId": "BGTK-1234-ABCD",
        "enumBackgroundTaskTypeId": "DOCUMENT_GENERATION",
        "taskStatus": "COMPLETED",
        "recordStatus": "SUCCEEDED",
        "relationType": "TARGET",
        "outputs": [
          {
            "recordOutputSimplyId": "BTRO-7890-UVWX",
            "outputKey": "document",
            "outputKind": "FILE",
            "status": "SUCCEEDED",
            "destinationWriteStatus": "WRITTEN",
            "destinationWriteMode": "REPLACE",
            "destinationDataFieldSimplyId": "FLDS-DOCS-0001",
            "result": { "filename": "welcome-letter.pdf", "contentType": "application/pdf" },
            "file": { "fileSimplyId": "FILE-2345-YZAB", "filename": "welcome-letter.pdf", "mimeType": "application/pdf" },
            "canDownload": true,
            "createdAt": "2026-07-07T15:04:01.000Z",
            "updatedAt": "2026-07-07T15:04:09.000Z"
          }
        ],
        "createdAt": "2026-07-07T15:02:11.000Z",
        "completedAt": "2026-07-07T15:04:09.000Z"
      }
    ],
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Per-output result values include only public display metadata (externalTemplateName, filename, contentType, fileSizeBytes); internal storage, AI, render, and user identifiers are redacted.

Download a Record Output

GET /v1/background-tasks/record-outputs/{recordOutputSimplyId}/download presigns the output's file and returns { "url", "expiresIn": 60, "filename" }. Only outputs with status SUCCEEDED are downloadable, and the caller must either be a team admin, be able to read the destination field the output was written to, or be the user who started the task. The canDownload flag in record history tells you ahead of time whether this call will succeed.

Typed Output Defaults

Teams can configure where typed task outputs are written on records. GET /v1/background-tasks/output-destinations/eligible lists candidate destination fields for a collection + task type + output key (all three query parameters required; sourceContentTemplateSimplyId optional). PUT /v1/background-tasks/output-defaults upserts a default with body fields dataCollectionSimplyId, enumBackgroundTaskTypeId, outputKey, dataFieldSimplyId, and writeMode (plus optional isEnabled and sourceContentTemplateSimplyId); DELETE /v1/background-tasks/output-defaults/{defaultSimplyId} removes one. These are first-party admin operations.

Migration from the Generated Files API

Breaking change (2026-06-28): the former Generated Files endpoints were removed and replaced by background-task record outputs. If you integrated against generated files, migrate as follows:

Removed endpoint	Replacement
Old data-record generated-files list endpoint	GET /v1/background-tasks/record-history?dataRecordSimplyId=... — each task entry's outputs array lists the record's generated artifacts.
Old generated-file detail endpoint	Read the output entry (metadata, status, file info) from the outputs array in record history.
Old generated-file download endpoint	GET /v1/background-tasks/record-outputs/{recordOutputSimplyId}/download — returns a presigned URL valid for 60 seconds.

Use the recordOutputSimplyId from record history where you previously stored a generated-file ID. Outputs written into a record field are also visible as regular field values — see Data Records and Files.

Usage Notes

• Creating tasks (POST /v1/background-tasks) is privileged: the body requires enumBackgroundTaskTypeId and accepts an optional queueData object, and creation is permission-checked per task type. Most integrations never create tasks directly — they receive a backgroundTaskSimplyId from another API (for example a website import) and poll it here.
• Presigned download URLs expire after 60 seconds; request them immediately before downloading and do not store them.
• lastUpdatedAt changes on every status or progress update, which makes it a cheap change indicator for polling clients.
• Errors are returned in the standard error envelope — see Error Handling.
• Questions or gaps in this reference? Use the feedback page or email developers@simply360.app.