API for presentation of goods and control direction of ICS2 consignments

About the service

This service is used for digital presentation of consignments. All goods filed in ICS2 are obligated to be presented upon arrival with a message to this API. From March 2023, this includes all consignments transported by air from third countries, and from June 3, 2024, it also applies to maritime consignments. Third countries in this context means countries outside the EU security zone (EU, Switzerland, Liechtenstein and Norway, excluding Svalbard). The same service can be used for joint presentation according to Entry Summary Declaration (ICS2) and Notification and Disclosure of Information (Melde- og opplysning) obligations. Presentation can be done by sending an Entry Summary Declaration (ENS), receptacle or individual house consignments. If a receptacle or an Entry Summary Declaration is presented, all individual consignments within will be considered presented. Furthermore, the party who has presented the consignments must use the routing service before the consignments eventualy may enter. When presenting ICS2 consignments, only routing of house consignment is relevant (for some parties, the service for routing at transport level may be relevant in relation to the Notification and Disclosure of Information obligation). Based on the result of the routing, the consignments that have received TO_CONTROL signal must be delivered to the agreed place of control. Consignments can not be released before TO_ENTRY signal has been received.

More background information on ICS2:

• ICS2 at toll.no
• Guidance documents from the EU
• Regulations concerning importation and exportation of goods (Movement of Goods Regulations)

If you have questions or suggestions regarding the API, please contact us at digitoll@toll.no

Workflow

The presentation services should be called as soon as the consignment has arrived. By including the requestId in every call, you as the consumer can ensure that a consignment is presented only once. Reusing the same requestId will result in validation errors. This is only a technical identification of each service call. The status of all requests can be retrieved by using the validation-status service.

Once a consignment has been correctly presented, the control direction signal can be retrieved from the routing service. This signal provides information on whether the consignment needs to be delivered for inspection or if it can be cleared and released to the recipient when other customs procedures are fulfilled. Control direction is performed at the individual consignment level (house consignment). When presenting at the receptacle or ENS (Entry Summary Declaration) level, the result for all individual consignments pre-notified within the respective receptacle or ENS must be retrieved. By using a marker as input, you can easily retrieve changes since the last call.

Interface Description

The services are made available over HTTPS, with authentication via Maskinporten.

     POST https://<env>/api/movement/presentation/v1/house-consignment
     POST https://<env>/api/movement/presentation/v1/receptacle
     POST https://<env>/api/movement/presentation/v1/entry-summary-declaration

     GET https://<env>/api/movement/presentation/v1/validation-status
     GET https://<env>/api/movement/routing/v1/house-consignment
        

where <env> is

• api.toll.no for production
• api-test.toll.no for playground (testing environment)

The API will be subject to changes as required by Norwegian Customs for the end goal of having a complete presentation service for all obligations when goods arrive. We will, as far as possible, make backwards compatible changes, but if breaking changes must be, the service will be versioned and users notified. Backwards compatible changes will be added without version updates or notifications.

API-documentation

• Movement – Presentation
• Movement – Routing

Code sets

Customs Office of presentation CL141

Customs Office of Presentation is validated against the EU code set Reference Data & Customs Offices List (europa.eu)

Transport document type CL754

CL754 Transport document type
Code	Description English	Description Norwegian
C624	Form 302 - Movement of military goods	Form 302 - Forflytning av forsvarsmateriell
C625	Rhine Manifest	Rhine manifest
C664	CN22 declaration according to Article 237 of the Regulation (ECC) No 2454/93	CN22 deklarasjon i henhold til Article 237 of the Regulation (ECC) No 2454/93
C665	CN23 declaration according to Article 237 of the Regulation (ECC) No 2454/93	CN23 deklarasjon i henhold til Article 237 of the Regulation (ECC) No 2454/93
N703	House waybill	Underfraktbrev (samlesending)
N704	Master bill of lading	Hovedkonossement
N705	Bill of lading	Konossoment
N714	House bill of lading	Underkonnossement (samlesending)
N720	Consignment note CIM	Fraktbrev CIM
N722	Road list - SMGS	SMGS-vegfraktbrev
N730	Road consignment note	Vegfraktbrev
N740	Air waybill	Flyfraktbrev
N741	Master airwaybill	Hovedflyfraktbrev
N750	Movement by post including parcel post	Forflytning med post inkludert pakkepost
N760	Multimodal / combined transport document	Dokument for kombinert transport

Authentication – Data exchange between the business sector and Norwegian Customs

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

• how to get started with integration via Maskinporten 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:movement/entry.

Testing

For testing purposes, the playground environment can be used.

The validation of submitted messages includes, among other things, a check to ensure that the specified references to Entry Summary Declaration, receptacle, and transport document number exist. The playground environment is not integrated with other systems, so the content is validated against a static dataset that contains a few values.

Entry Summary Declaration MRN	Receptacle ID	TransportDocumentHouseLevel – documentNumber	TransportDocumentHouseLevel – type	ContainerId	Routing
23NO00000000000001	GBASFZMLBKONAUN30001001019999	NO100000001MU	N750	–	TO_CONTROL
23NO00000000000002	GBASFZMLBKONAUN30001001019999	NO100000002MU	N750	–	TO_ENTRY
23NO00000000000003	–	HC001	N740	–	TO_ENTRY
23NO00000000000003	–	HC002	N740	–	TO_CONTROL
23NO00000000000004	–	HC001	N703	–	TO_CONTROL
23NO00000000000004	–	HC002	N703	–	TO_ENTRY
23NO00000000000005	–	HC003	N714	JARU0000010	TO_CONTROL
23NO00000000000005	–	HC004	N714	JARU0000026	TO_ENTRY

Both presentation and routing services will give responses based on these existing data. Other input values will result in validation errors upon submission.