Tax Returns

Tax returns represent annual income tax filings (skattemelding for upersonlige skattytere) submitted to Skatteetaten via the Altinn platform. The API allows you to preview tax return data from accounting, fetch pre-filled data from Skatteetaten, validate before submission, and submit the final return.

Endpoints

List Tax Returns

GET /api/v2/tax-returns

Retrieves a paginated list of tax return submissions.

Query Parameters

Response

{
  "data": [
    {
      "id": 1,
      "client_account_id": 7,
      "reporting_year": 2025,
      "from_date": "2025-01-01",
      "to_date": "2025-12-31",
      "tax_authority_reference": "ref-12345",
      "altinn_instance_id": "abc-def-123",
      "status": "SUBMITTED",
      "submitted_at": "2026-03-10T14:30:00Z",
      "error_message": null,
      "receipt_voucher_id": 456,
      "created_at": "2026-03-10T14:00:00Z",
      "created_by_id": 7
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Get Tax Return

GET /api/v2/tax-returns/{id}

Retrieves a specific tax return by ID.

Query Parameters

Response

{
  "id": 1,
  "client_account_id": 7,
  "reporting_year": 2025,
  "from_date": "2025-01-01",
  "to_date": "2025-12-31",
  "tax_authority_reference": "ref-12345",
  "altinn_instance_id": "abc-def-123",
  "status": "SUBMITTED",
  "submitted_at": "2026-03-10T14:30:00Z",
  "error_message": null,
  "receipt_voucher_id": 456,
  "created_at": "2026-03-10T14:00:00Z",
  "created_by_id": 7
}

Get Tax Return Status

GET /api/v2/tax-returns/{id}/status

Gets the current status of a tax return. If the return has been submitted and has an Altinn instance ID, the system will attempt to refresh the status from Altinn before responding.

Response

Returns the tax return object with the latest status.

Preview Tax Return

GET /api/v2/tax-returns/preview

Generates a preview of the tax return with auto-populated data from accounting records. Use this to review income statement, balance sheet, and summary totals with any validation issues before submission.

Query Parameters

Response

Returns a preview object with accounting data, tax calculations, and validation issues. The exact structure depends on the company type and tax form.

Fetch Pre-filled Data

POST /api/v2/tax-returns/{year}/fetch-prefilled

Fetches pre-filled tax return data from Skatteetaten for the given year. This retrieves data that the tax authority already has on file (e.g., from third-party reports).

Query Parameters

Response

Returns the pre-filled data from Skatteetaten as JSON.

Validate Tax Return

POST /api/v2/tax-returns/{year}/validate

Validates the tax return XML with Skatteetaten without submitting. Use this to catch errors before final submission.

Request Body

Query Parameters

Response

Returns the validation result from Skatteetaten, including any errors or warnings.

Submit Tax Return

POST /api/v2/tax-returns

Submits a tax return to Skatteetaten via Altinn.

Request Body

Example Request

{
  "client_account_id": 7,
  "reporting_year": 2025,
  "ignore_warnings": true
}

Response

Returns the created tax return object with status SUBMITTED or DRAFT depending on the submission result.

Cancel Tax Return

POST /api/v2/tax-returns/{id}/cancel

Cancels a draft or submitted tax return. Only returns with status DRAFT or SUBMITTED can be cancelled.

Response

Returns the tax return with status set to CANCELLED.

Cancel Validation

Attempting to cancel a tax return that is already APPROVED, REJECTED, or CANCELLED will return a 400 Bad Request error:

{
  "error": "Cannot cancel tax return with status APPROVED",
  "status": 400
}

Tax Return Statuses

Error Responses

Business Rules

1. Tax returns are scoped to a specific client account and reporting year
2. Users must have access to the client account to manage its tax returns
3. The preview endpoint pulls data directly from the accounting ledger
4. Pre-filled data and validation use Skatteetaten’s API via the Altinn integration
5. Only DRAFT and SUBMITTED returns can be cancelled
6. Status refreshes happen automatically when checking the status of a submitted return
7. The receipt voucher (PDF from Skatteetaten) is stored and linked via receipt_voucher_id

Typical Workflow

1. Preview - Call the preview endpoint to see accounting data and validation issues
2. Fetch pre-filled - Retrieve data Skatteetaten already has on file
3. Validate - Run validation against Skatteetaten to catch errors
4. Submit - Submit the final tax return
5. Monitor - Check status for approval or rejection