Migrating from API v1 to API v3

API v1 will be shut down in Q3 2025

To ensure continued access and compatibility, all users must transition from API v1 to the new and improved API v3. This guide is designed to help you make the switch as smoothly as possible.

API v3 introduces important changes, including updated request headers and renamed fields. In this guide, you’ll find:

  • Instructions on how to set up the required access credentials for API v3

  • A detailed mapping between old and new field names

  • Tips and tricks highlighting useful new features in API v3

Follow the steps below to complete your migration efficiently and with confidence.

You can find the API documentation for API v1 here.

Updated request headers in API v3

API v3 introduces new required headers for all requests. Here's a breakdown of what's changed:

  • tb-key
    This replaces the old key header used in API v1.
    In v1, the API key was set using the header key.
    In v3, it must be set using the header tb-key.
    A Tidsbanken administrator can find this key by following this guide.

  • x-api-version
    This must be set to 3.0 to specify which version of the API you are targeting.

  • Ocp-Apim-Subscription-Key
    This is your subscription key. It must be included in all requests, alongside the tb-key. See the next step for how to create one.

Make sure all three headers are present in every request to authenticate properly and access the correct environment.

User and subscription key

To start using API v3, you'll need to generate a subscription key from the API portal. This key is required in all requests, along with your customer-specific API key. Follow the steps below to set it up:

Step 1:
Create a user and log in

Go to the login page, create a user if you don't already have one, and log in. Then click Products in the top-right menu.

Step 2:
Subscribe to the Public Standard product

Click on the Public Standard product, enter a name of your choice, and click the subscribe button.

Step 3:
Access your API key

If you need to use the key outside of the documentation page, go to Profile from the menu to find it.

Pagination in API v3

To help keep integrations efficient and performant, API v3 uses server-side pagination by default. This means large result sets are split into pages—typically 10,000 items per page—and returned with a helpful @odata.nextLink. You simply follow this link to fetch the next page of results.

You can also use top and skip for client-side paging, but note that there is a maximum page size currently set to 10,000. This limit is enforced even if you request a higher number—and while the limit may be increased in the future without notice, we still recommend relying on @odata.nextLink for optimal stability.

For more on how this works and when to use each approach, check out our pagination guide.

Field changes and endpoint consolidation in API v3

API v3 introduces significant improvements in both structure and naming—making integration development clearer, more consistent, and easier to maintain.

What’s changed?

Field names have been renamed

Many fields from API v1 have been updated in v3 to better describe the data they represent. These new names aim to:

  • Improve readability for developers

  • Reduce ambiguity across the API

  • Reflect clearer and more precise semantics

The result is a more intuitive and developer-friendly data model that simplifies integration work and reduces potential for confusion.

Multiple endpoints are now merged

Several related endpoints from API v1 have been grouped into broader and more functional APIs in v3. This consolidation:

  • Reduces fragmentation

  • Simplifies access to related data

  • Promotes better structure and reuse of logic across domains

API Prosjekt

Combines
Prosjekter, Prosjektlinjer and Aktiviteter

Also includes
Varer, Varetransaksjoner and Kunder

Renamed fields

API documentation

API Ansatt

Combines
Ansatte and Avdelinger

Also includes
Stemplekort, Ressurstyper and Ansattgrupper

Renamed fields

API documentation

API Timelinje

Combines
Eksporter, Lønnslinjer and Timelister

Also includes
Slettede timelinjer and Timesaldo

Renamed fields

API documentation

API Arbeidstidsregler

Combines
Arbeidstyper and Arter (Lønnsarter)

Renamed fields

API documentation

API Omsetning

Based on
Omsetning

Renamed fields

API documentation

API Planlegging

Based on
Plan

Renamed fields

API documentation

Tips and tricks for API v3

API v3 includes several helpful features and improvements that can make your development experience smoother and more efficient—once you're familiar with them.

We’ve gathered a collection of practical tips, examples, and lesser-known capabilities to help you get the most out of the new version.

➡️ Explore the guide here

API v1 will be shut down in Q3 2025