System Tasks

System tasks represent long-running background operations within a client account, such as fetching tax cards from Skatteetaten, submitting a-meldinger, or syncing VAT returns. The API allows you to check which tasks are currently running.

Task state is stored in Redis with automatic expiry (TTL), so tasks that crash or hang are automatically cleaned up. Real-time updates are pushed to connected clients via Pusher events.

Endpoints

List Running Tasks

GET /api/v2/system-tasks

Returns all currently running system tasks for a client account.

Query Parameters

Parameter	Type	Required	Description
client_account_id	integer	Yes	The client account to list running tasks for

Response

{
  "data": [
    {
      "task_type": "FETCH_TAX_CARDS",
      "started_at": "2024-06-01T10:00:00+00:00",
      "meta": {
        "income_year": 2024,
        "business_partner_id": 56
      }
    },
    {
      "task_type": "VAT_RETURN_SYNC",
      "started_at": "2024-06-01T10:05:00+00:00",
      "meta": {}
    }
  ]
}

Note: This endpoint does not use pagination. It returns all currently running tasks for the client account. In practice, only a handful of tasks run concurrently.

Task Object

Field	Type	Description
task_type	string	Identifier for the type of background operation (see Known Task Types)
started_at	datetime	UTC timestamp when the task was started
meta	object	Optional metadata included when the task was started (varies by task type)

Known Task Types

Task Type	Description	Typical TTL
FETCH_TAX_CARDS	Fetching employee tax cards from Skatteetaten	10 minutes
FETCH_GARNISHMENTS	Fetching wage garnishment orders from Skatteetaten	10 minutes
VAT_RETURN_SYNC	Synchronizing VAT return data	60 minutes
AMELDING_SUBMIT	Submitting an a-melding to Skatteetaten	varies

Real-time Updates

System task events are pushed via Pusher on the channel data-events;{client_account_id}:

Event	Description
`create_system_task`	A new task has started
`update_system_task`	A task has completed or failed

The update_system_task event includes a status field with value "completed" or "failed", along with optional result_meta containing task-specific results (e.g., {"count": 5} for the number of items processed).

Error Responses

Status Code	Description
400	Invalid request (missing `client_account_id`)
403	Forbidden (no access to client account)

Business Rules

System tasks auto-expire based on their TTL — if a task crashes without completing, it will be automatically cleaned up
The endpoint only returns currently running tasks. Completed or failed tasks are removed immediately
Task metadata varies by task type and may include context like income_year, business_partner_id, or period information

A-melding Submissions — a-melding reporting (triggers AMELDING_SUBMIT tasks)
Payroll Tax Cards — tax card management (triggers FETCH_TAX_CARDS tasks)
Payroll Garnishments — garnishment management (triggers FETCH_GARNISHMENTS tasks)
VAT Returns — VAT return submissions (triggers VAT_RETURN_SYNC tasks)