About the service
This service is used for the digital fulfillment of presentation obligations. All goods that have been filed in ICS2 must be presented through this API. From March 2023, this includes all goods transported by air from third countries, and from June 3, 2024, it will also apply to goods transported by other means of transport. Third countries refer to nations outside the European security zone (EU, Switzerland, Liechtenstein, and Norway excluding Svalbard). Eventually, the same service can be used for national duties as well. Presentation can be made by submitting an entire entry summary declaration (ENS), a receptacle or individual house consignments. If a receptacle or an entry summary declaration is presented, all individual consignments under it will be presented as well. Furthermore, the operator presenting the consignments should also use the routing service to receive control routing before the goods can be released. When presenting ICS2 consignments, routing will be at House Consignment-level (for certain operators, the routing service at the transport level may be relevant in regard to other national obligations). Based on the routing response, the consignments should be promptly delivered to the agreed location if the signal TO_CONTROL is received. The consignments should not be released until the signal TO_ENTRY is received
More background information on ICS2:
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. 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 will 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
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 invironment is not integraded 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 | ||
23NO00000000000002 | GBASFZMLBKONAUN30001001019999 | NO100000002MU | N750 | ||
23NO00000000000003 | – | HC001 | N740 | ||
23NO00000000000003 | – | HC002 | N740 | ||
23NO00000000000004 | – | HC001 | N703 | ||
23NO00000000000004 | – | HC002 | N703 | ||
23NO00000000000005 | – | HC004 | 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.
Feedback and contact
If you have questions or suggestions regarding the API, please email us at ics2-kontakt@toll.no