About the service

The data sharing service is a retrieval service for declaration data. It is as general as possible and without aggregation, so that consumers can process, summarise, and combine declaration data as they see fit.

The service is only available for Norwegian government agencies / partners with a specific data sharing agreement.

The service provides a series of events, where each individual event concerns one goods item with associated information from the declaration. For a declaration containing several goods items, the same declaration information will therefore be repeated in each event relating to the goods items in that declaration. Events are published when all our processing has been completed, typically when the goods have been released, but also when corrections have been fully processed, and not while processing is still ongoing. We do not publish in real time. It is also important to note that the service does not include

• transport information from the Digitoll/MO solutions
• data from solutions associated with operators on the continental shelf or Svalbard, where import/export is not declared through the Tvinn system

Interface description

General information about the event-based service

The service is designed as a "feed" or event stream with no theoretical end, returning a number of events in each call. Long polling or similar extensions are not offered from us; we assume that regular calls to the service will be a simple and well-functioning pattern for this type of service.

As a client, you generally decide yourself how often to call the service, within the specified limits. You normally provide the ID of the latest occurrence you read (referred to as the "marker"), and will receive data newer than the marker. Since there is a limit to the number of events returned per call, you may need to call the service several times before you are up to date. Given the nature of the service, we therefore ask you to align the call frequency with the amount of data you receive. If we find that clients are polling too frequently, we will have to consider introducing automated restrictions, although we would prefer to avoid doing so. Based on the expected initial data volume, we assume that approximately once per minute, followed immediately by additional calls if the maximum number of events is returned, would be a reasonable starting point.

The service will retain historical data for a certain number of months. The number of months may change in the future. Please also note that there will be different event types, some of which may remove data from the total; you as the client are expected to keep track of this. This is not intended to be used as a lookup service. The normal pattern should be that you as the client retrieve each event only once and store what you need in your own systems. The option to "rewind" is provided to cover operational disruptions and unexpected situations. As a client, you must also be able to tolerate occasional duplicate data. We recommend that you maintain a record of the IDs of received events for at least as many months as the service offers, so that you can filter out any duplicates. This may be a disadvantage for you, but we do this to make it easier to parallelize our services in line with performance requirements.

The data stream is not updated in real time with respect to data received by Norwegian Customs. Expect there to be a delay in the order of one hour between our completion of processing and the subsequent publication of events.

As a consumer, you are responsible for defining, establishing the legal basis for, and following up on how old the data you retain may be. Norwegian Customs will not send deletion messages for old data, since the legal bases of different consumers may vary.

Data restrictions per consumer

We may impose restrictions on both

• which data fields we share with you as a client; this may be fewer than the full set contained in the data schema, and depends on cooperation agreements and legal bases
• which goods items you receive, normally based on commodity code; likewise customized per client based on agreements and legal bases
  • Note that the agreements applies at the time of publishing. Extensions on the agreements will normally not be given retroactive effect, and if you as a client receive a narrower legal basis, it is your responsibility to discard data you have already received, or data that exists as events published before the change came into effect.
  • Similarly, the customs tariff may change over time. We will not republish older events in connection with such changes.

Corrections

Corrections of customs declarations occur regularly. In such cases, we will send out

1. deletion events for goods items that have been removed from or changed in the declaration (in practice, this will often be all goods items in a declaration, since there is not necessarily any link at the goods item level between the old and the new declaration),
2. possible subsequent added events for goods items that are new or changed

In both cases, we will refer back to the previous and the original declaration (if there have been several changes to a declaration over time, these two may be different). One or both of these may be unknown to you as a client, as those earlier versions may not have contained goods items that were within your selection. Note that "changes" may occur which result in the same "now" state as "previous" state; this can happen if changes are made to information that is not included in your dataset (or, for that matter, in any of the client's datasets), but which nevertheless trigger new publication and new IDs.

Technical details

A maximum of 1,000 events is returned per call. As a consumer, you may choose to receive fewer events in a given call, but not more.

The structure of the data returned may vary, but will be in JSON format. We will describe formats using JSON Schema. The data structures will also be described in OpenAPI specifications (Swagger) in the test environment, but not in production.

The service is based on REST over HTTPS and is available at:

GET https://<env>/api/declaration/declaration-item-feed/v1/

• <env> is replaced by
  • api.toll.no for production
  • api-test.toll.no for playground (test environment)

See the detailed API documentation here.

JSON schema

In short, an event consists of an envelope part and a data part. The envelope part contains metadata about the event, including an event ID and the time when the event was created. The data part contains information about the relevant goods item together with associated declaration information, in which the field names follows the EUCDM standard as close as possible.

{
  "metadata": {
    "eventId": "aec5b761-fa41-456a-97c0-950800aab20e",
    "created": "2026-01-19T17:29:10Z",
    "eventType": "ITEM_ADDED"
  },
  "data": {
  }
}

A link to the schema will be added here later.

Event type

As a client, you must assume that new events may be added to a declaration over time.

1. ITEM_REMOVED is used for goods items that have been removed from the declaration, or from your scope as a client. They are also sent before ITEM_ADDED for changed goods items. This event contains only the envelope part, with an ID pointing to the goods item that has been changed/removed. You as the client are expected to have stored the ID.
2. ITEM_ADDED is used for new and changed goods items, and contains both the envelope and data part because the content is new information.

Parameters

We provide a set of parameters that are standard for APIs of this type:

1. last=ID specifies the ID of the latest occurrence the consumer has read, the marker; the returned dataset will continue after this. Note:
   • the specified occurrence will not be included in the dataset
   • there is no guarantee that IDs in calls form a monotonically increasing sequence without gaps. On the contrary, you must assume that they do not. We use UUIDs
   • if no event with the specified ID exists, status 404 (Not found) is returned

2. timestamp=YYYYMMDDTHHmmssZ This may be used instead of the previous parameter if the ID is not known, and specifies the publication timestamp. Occurrences with a timestamp >= this value will be included in the result. Note:
   • depending on the parameter value, there may be overlap or gaps compared with previous calls
   • as mentioned, there is an "age limit" for the oldest occurrence, meaning there is no guarantee that data as old as the supplied parameter actually exists

3. skip=N to skip N occurrences that would otherwise have been included in the selection; included mostly for compatibility with lookup services
4. max=N to request a maximum number of occurrences that is less than or equal to (not greater than), the maximum number for this service

Return values

200 OK — the call is OK. However, the returned dataset can be empty, which can happen if the parameters are OK but there is no new data according to the submitted parameters. Also note that more data may be available than what is returned in this call; if the number of returned events equals the maximum limit (either set by the service or by the max parameter), the service should be called again to retrieve the next batch. This is not explicitly signalled through the return status.

401 Unauthorized — used if the client is not correctly authenticated, meaning either that it has not authenticated through Maskinporten, or that it does not have agreements permitting data to be disclosed through this service

404 Not found — if an unknown ID is provided as the last parameter

Authentication

Our APIs use Maskinporten for identity and access management. On the page Maskinporten - Norwegian Customs you will find information on

• how to get started with integration via Maskinporten if you have not done so before, including a registration form for access to Norwegian Customs
• Access management for our APIs
• Setting up a client for authentication via Maskinporten
• Operations and monitoring/troubleshooting.

The scope used for this API is toll:declaration.feed.