API Documentation

Introduction

The API is designed to facilitate the reporting of a child’s birth to Skatteverket (the Swedish Tax Agency). This API allows healthcare providers to submit birth reports, ensuring that newborns are correctly registered and assigned a personal identity number when applicable.

Key Features

• Birth Reporting: Submit a birth report with details about the child, mother, and father.

• Automated Processing: If the report meets all criteria, a personal identity number is assigned automatically.

• Manual Review Cases: Certain conditions trigger a manual review process (e.g., mother not registered in Sweden, duplicate report detection).

• Error Handling: Clear error messages and response codes guide integrators in handling edge cases and failures.

Main Endpoint

• POST /v1/birthreport

• Purpose: Submit a birth report.

• Request Body: Includes details such as the mother’s identity, child’s birth date, and reporting clinic.

• Headers: A trace ID (x-trace-id) for logging.

• Responses:

  • 201 Created: The birth report was successfully processed, and a personal identity number was assigned.

  • 202 Accepted: The birth report was received but requires manual review.

  • 400 Bad Request: The request contained invalid or missing fields.

  • 403 Forbidden: The request was not authorized.

  • 502 Bad Gateway: A communication error occurred with Skatteverket.

This API ensures a structured and efficient process for registering newborns, minimising manual work while allowing necessary oversight for special cases. For full request and response details, refer to the API specification.

Getting Started

The API allows healthcare providers to report the birth of a child to Skatteverket for registration and potential assignment of a personal identity number. Follow these steps to get started with your integration.

Download the API Specification

Start by downloading the OpenAPI specification to explore the available endpoints and payloads:

📄 Download: Fodelseanmalan OpenAPI v2.0.0 (JSON format)

You can use the specification with tools like Postman, Swagger UI, or OpenAPI Code Generators to generate client SDKs and test API behavior.

Issue certificate

The API uses mutual TLS (mTLS) for secure communication. This means both your client and the API server must authenticate each other using valid certificates.

To connect to the test environments, you’ll need a SITHS funktionscertifikat for test issued by:

TEST SITHS e-id Function CA v1

Request Access to the Test Environment

Once you have a valid certificate, request access to the Test environment via Inera Kundportal. In your request, include:

• Environment name: Test

• Details of the certificate you will use

The Test environment includes a “fake Skatteverket” and test data for both successful and failing scenarios.

Read more in the Environment Overview.

Explore the API Through Postman

After gaining access, use the Postman test suite (available for download) to explore the API functionality. It includes predefined test cases to help you:

• Send birth reports

• Trigger different response scenarios (success, failure, manual handling, etc.)

This step helps you understand the API flow before starting your own implementation.

Postman collection available here.

Next Step: Implementation and Anslutningsprocess

When you’re ready to move forward:

• Start implementing integration to the API

• Perform thorough integration testing

• Begin the Anslutningsprocess with Inera using the Stage environment

Access to the Production environment requires that you are officially onboarded (Ansluten).

More on onboarding and the Anslutningsprocess in this section.

Environment Overview

The API is available in three separate environments, each serving a specific purpose in the integration lifecycle: development, testing, staging, and production. All environments require mutual TLS (mTLS) for secure communication and enforce strict client authorization.

Test

The Test environment is designed to support development and initial testing of integrations. It includes a simulated version of Skatteverket and offers a wide range of test data, including:

• Successful integration scenarios

• Scenarios designed to trigger various types of failures

A downloadable Postman test suite is available, providing detailed examples and expected responses for each test case. This environment is ideal for developers who are building and debugging their integrations.

Stage

The Stage environment connects to Skatteverket’s test environment for Födelse and is intended for:

• The Anslutningsprocess (connection/onboarding process)

• Full end-to-end testing with Skatteverket

This environment closely mimics the production setup and is typically used during the final stages of integration before going live.

Production

The Production environment is the live production environment. Access is restricted to consumers who have completed the Anslutningsprocess and are officially approved (Ansluten).

This environment handles real data and should only be used by fully onboarded consumers with production-ready systems.

Security and Access Requirements

All environments enforce the following:

• Mutual TLS (mTLS) for secure transport

• Client authorization based on the presented certificate

The test environments (Test and Stage) require a SITHS funktionscertifikat for test, issued by:

TEST SITHS e-id Function CA v1

The production environment requires a SITHS funktionscertifikat for production, issued by:

SITHS e-id Function CA v1

Requesting Access

To request access to any environment, create a support ticket in Inera Kundportal. The ticket must include details about the certificate that will be used for authentication. The Base Url for the environment will be provided through the ticket.

API Specification

The API is described using the OpenAPI Specification (version 3.0). You can download the full specification in JSON format and use it with tools like Postman, Swagger UI, or OpenAPI code generators.

📄 Download Fodelseanmalan OpenAPI Specification (JSON)

The specification includes all available endpoints, request and response structures, status codes, data types — as well as sample responses for all supported scenarios (both successful and failing cases).

Troubleshooting

If you encounter issues while using the API, the following tips can help speed up the support and debugging process.

Use of x-trace-id

We recommend including the optional header x-trace-id in all your API requests:

This trace ID is logged on our side and can be used to identify and follow your specific request through our system.

When registering a support ticket, please include the trace ID so we can more easily locate the related logs and speed up analysis.

Testing with Postman in Test

If you’re using the Test environment and encounter unexpected behavior:

• Try reproducing the scenario using the provided Postman test suite

• This helps rule out issues in your integration code and isolates the API behavior

The Postman collection includes predefined test cases that reflect both successful and failing scenarios.

Running these tests can help you confirm whether the problem lies in your implementation or in the request data.

Files